How Loop is built.
Loop is a small product over a deliberately serious engine. This page is the part you can’t see from the landing page: where the AI is allowed to act, where it isn’t, and how both are enforced. Each section names the repository files where its claims can be checked.
LLMs propose. Deterministic infrastructure disposes.
Exactly four LLM node classes exist, and all of them produce structured candidates: a strategy, a plan, a reflection summary, a user-facing explanation. Everything that decides is ordinary, testable code — routing, validation, scheduling, the approval gate, calendar writes, telemetry, drift classification. Model output is parsed into typed contracts and validated before any consumer sees it; prose never becomes control-plane state.
The boundary is mechanical, not aspirational: only the llm_nodes package may import the model SDK, and import-linter contracts enforce that in CI.
Checkable in · docs/axioms/01-system-boundaries.md · docs/decisions/ADR-0001-deterministic-control-plane.md · docs/decisions/ADR-0006-llm-never-touches-the-calendar.md · backend/.importlinter
Nothing reaches your calendar that you didn’t approve.
One writer, one gate
The scheduler only drafts. A single Calendar Write Manager performs writes, and it refuses any write that doesn’t carry an approval event id, run id, task id, and plan version.
Hash-locked approvals
At write time the approved payload hash is recomputed against the live draft under the recorded canonicalization version. If anything changed since you clicked approve, the write is refused.
Dry-run, verify, roll back
Every external side effect supports dry-run, duplicate detection, a verification read after writing, and rollback from stored event mappings. Anything unverified blocks the plan from activating.
Typed failures, bounded repair
Every failure carries a typed reason_code. Repair is capped — two attempts per artifact, two scheduler iterations — then an honest, recoverable failure instead of a silent retry loop.
Immutable plan versions
The active plan is never edited in place. Every change is a new version, and what you approve is a deterministic diff against the last one.
Injected time and identifiers
The clock and ID generation are injected dependencies, so every safety path above — including failure and rollback — replays deterministically in tests.
Checkable in · docs/axioms/06-calendar-safety.md · docs/axioms/16-reliability-patterns.md · docs/axioms/15-plan-versioning-and-diffs.md · docs/specs/approval-event.schema.md
Prompt changes can’t ship unmeasured.
The LLM edge is treated like any other dependency: measured, versioned, and gated. Live calls never run in CI — committed recordings do.
Capture
An operator tool records live model calls — inputs, outputs, token counts, cost. Recordings are committed to the repository as plain data.
Grade deterministically
A separate CI job re-grades committed recordings with pure functions: schema validity, repair recovery, plan-shape facts. Same input, same grade, every run.
Judge, advisory only
An LLM judge scores recorded prose for tone and specificity — offline tooling only, deliberately not a workflow node. Its scores never gate a merge and never feed runtime behavior.
Pin the prompts
Each node’s prompt_version is pinned to the prompt bytes by SHA-256 at two layers — the system prompt and the full rendered call. Edit a prompt without bumping the version and a test fails.
Checkable in · docs/axioms/22-llm-evaluation-and-observability.md · backend/Makefile (eval-gate) · .github/workflows/ci.yml · backend/tests/llm_nodes/test_prompt_versions.py
Measured at the commit that shipped this page.
Backend tests, green in this page’s shipping commit alongside lint, strict typechecking, and a schema-drift check. All deterministic: no network, injected clock, fixture LLM nodes.
Frontend tests over the SPA’s deterministic logic — reconciliation, drag math, approval and recovery states.
Axiom documents (00–22): the written law of the system. Code that contradicts an axiom is, by definition, a bug.
Architecture decision records, including the two that define the product: the control plane is deterministic, and the LLM never touches the calendar.
Expected monthly LLM spend per active user, under an $8 hard cap (about 5× headroom). A full onboarding costs ~$0.28; a replan cycle ~$0.22. Per-node caps and pricing tables live in the cost axiom and are re-derived when prices drift.
One number this page won’t give you: accuracy. Validation thresholds, drift thresholds, and source-confidence scores are heuristic priors until calibrated against real usage — the product interface says so, and so does this page.
Checkable in · backend/Makefile (check) · docs/axioms/09-cost-and-metrics.md · docs/axioms/08-rag-source-claims.md · docs/axioms (count) · docs/decisions (count)
Built by one person, on purpose.
Loop is designed and built by Shawn Liu: a Python backend (FastAPI over a deterministic core), a React SPA, SQLite, and a single Fly.io machine — with the landing page and this one served as static files. A code walkthrough is available on request.