> ## Documentation Index
> Fetch the complete documentation index at: https://helloluciallc.com/llms.txt
> Use this file to discover all available pages before exploring further.
# LIEA doctrine
> The Lucia Intelligence Engine Algorithm at doctrine level: everything feeds the Algorithm, the Algorithm decides what surfaces, the instruments come before the intelligence, and every change shows its effects in plain English.
LIEA is proprietary. This page records what the Algorithm is, the laws that
govern changing it, and the instruments that keep it honest. It carries no
weights, thresholds, budgets, scoring formulas or reason-code semantics; those
live in the Engine and on the access-walled living spec.
## What LIEA is
The Lucia Intelligence Engine Algorithm is a **deterministic ranker of operator
attention**. It reads the property's state, decides what deserves the owner's
attention and in what order, and emits the ranked signals the admin renders as
the **Signal Stream**. It is code, not a model. It runs the same way on the
same inputs every time, under an injected property clock.
```text theme={"dark"}
inputs (property-scoped)
guest and booking state
property context and the property clock
financial truth from Stripe and the durable ledger
the maintenance inbox
→ normalize → lifecycle → candidates → score → eligibility → quality
→ sort → diversity → freshness → arrival escalation → budgets → overflow → rank
→ signals[] (contract_version 1)
→ operator projection (priority, dismiss, reminder)
→ Signal Stream
```
Four categories are live in code: **payment, arrival, concierge,
maintenance**. Push notifications bypass the Algorithm entirely.
The canonical picture is the **LIEA Signal Pipeline chart**, source-controlled
in the Engine repository and kept true by the chart-drift test. Its canonical
home is Algorithm Mermaid Chart Design Rendering (ALGO-25); the chart is cited
here, not redrawn.
## The doctrine
**Everything feeds the Algorithm; the Algorithm decides what surfaces.** Every
signal reaches the owner through the Algorithm's ranking. Focus with Lucia
carries the served stream as served inside its house pack and never re-ranks
it; the model is the voice and the hands, never the ranker. Founder doctrine
(2026-09-05): "I'm chatting with a highly customized, trained and tuned Fable
using the platform, calendar and algorithm as guardrails and the temporal
brain for bookings ... Fable is smart enough to help the human property owner
through these steps by knowing what tools are available to Fable/Lucia at the
time on that step."
**Instruments before intelligence.** Founder-ratified 2026-09-02 (ALGO-8):
instruments first, diagnosis in parallel, behaviour changes only once
measurable. No weight is retuned before the change can be measured.
**Every Algorithm change shows its effects in plain English.** The founder's
law (HLLC-29, 2026-08-29): "Any merge that changes Algorithm behavior must
produce a founder-readable before/after record. If the behavioral effect cannot
be explained plainly and verified against representative scenarios, the change
is not ready to be treated as safely understood, even if CI passes." The record
answers eight questions: which real-world inputs now produce different results;
which classification, rank, threshold, weight or reason code changed; what
Lucia did before; what she will do now; whether the change was intentional;
who could be affected; what evidence shows the new behaviour is correct; what
uncertainty remains.
**Adversarial review at every gate.** Every Algorithm diff gets a Codex
adversarial review, up to three rounds before the founder decides ship or kill
(ALGO-2; ratified on ALGO-8, 2026-09-02).
**One honest contract.** The served output declares one contract version; an
unknown reason code throws in strict mode and is dropped in production; every
declared code must be reached by a corpus fixture; dead ranking code is deleted
rather than documented as live (ALGO-8).
**Before any weight is retuned, a ledger.** The decision ledger records every
evaluation, every candidate and what became of it, and joins the owner's later
actions to that evaluation, so precision, false negatives and overrides become
measurable (ALGO-9).
## The instruments, as they stand on 2026-09-10
| Instrument | What it does | Status |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Contract conformance suite (`npm run algorithm:contract:test`) | Enforces `contract_version 1` on every `npm test`: vocabularies, strict-mode normalizers, every declared code reached by a fixture | Served on Engine dev since 2026-09-02 (ALGO-8 phase 02a, `5fe85e6`); endpoint meta carries `contract_version: 1`, `design_version: "v0.2.4"`, `version: "v0.2.1"`. Phase 02b (advance the runtime version when the corpus is green) outstanding |
| Replay harness (`npm run algorithm:replay -- --old --new `) | Runs the fixed corpus through two Algorithm revisions under pinned clocks and prints the old-to-new table; "no behavioral change" is the explicit happy path; `--fail-on-change` for the gate | Completed 2026-09-03 (HLLC-29, `f99ea20`); corpus 44 scenarios at merge, 47 scenarios by 2026-09-07 |
| Chart-drift test (`npm run algorithm:chart:test`) | Reads code truth and compares it to the LIEA pipeline chart: reason-code counts and versions, supported categories, budgets, freshness, diversity, overflow, and the stage chain; a drifted box fails the build and CI posts one drift comment on ALGO-25 | Completed 2026-09-02 (ALGO-28, `ede6cb8`) |
| Living spec v0.3.0 | Describes the Engine as on `dev` with a version block and one change-log row per merged Algorithm change; open founder rulings written as open questions until ratified | Completed 2026-09-03 (ALGO-35); access-walled, cited by name only |
| Decision ledger | Durable record of every evaluation and outcome | Design ratified 2026-09-02 (ALGO-9); **not built** |
| Focus bank | The Focus surface's own bank (pack mode on every push, live on Fable at the gate) | 23 cases by 2026-09-07; a Focus instrument, not a ranking instrument |
Every Fable-era merge (ALGO-39, ALGO-40, LUCI-189, LUCI-211, LUCI-214, ALGO-49)
posted "Algorithm replay: no behavioral change" on its record. The Algorithm's
ranking did not move while Lucia's voice did.
## Ownership
The Algorithm files are owned by one seat, the Algorithm Engineer; the
Algorithm Scientist owns what should change and never merges; the Algorithm
Evaluator owns the instruments; a Librarian keeps the living spec and a QA seat
runs black-box scenarios against dev (Algorithm crew roster, ALGO-2, Completed
2026-09-03). Every seat works branch-per-issue; one gate merges. The founder
reads the before/after on every merge.
## The proprietary boundary
The Algorithm brain deep dive (ALGO-1, 2026-09-02) is the audit of record and
lives only inside the workspace. What this library publishes is bounded to:
what LIEA is, the four categories, the pipeline's stage names, the laws, and
the instruments. Weights, thresholds, budgets, scoring shape, reason-code names
and counts, and file-level internals do not publish. The living spec and the
chart's rendered assets are access-walled or workspace-authenticated by design.
## Not current
* The decision ledger (ALGO-9) is ratified, not built.
* Phase 02b of the contract (ALGO-8) and the runtime version advance are
outstanding.
* The Brain quality eval bank (217 prompts) is not green and is not the gate;
the standing gate for language changes is identical failing sets before and
after (ALGO-36, Backlog).
## See also
* [Focus Ops Intelligence](/lucia/intelligence/focus-ops-intelligence)
* [START HERE - Intelligence Layer](/lucia/intelligence/start-here-intelligence-layer)
* [Model Layer](/lucia/infrastructure/model-layer)
* [GitHub and Branch Discipline](/lucia/infrastructure/github-and-branch-discipline)
* [Evaluation System](/lucia/evaluation/start-here-evaluation-system)
* [Truth State Doctrine](/lucia/foundation/truth-state-doctrine)