The two loops

Alloy is two loops around a corpus. The production loop makes docs; the feedback loop keeps them honest. Understanding them is understanding the whole system.

The production loop

Left to right: source becomes a validated, stamped doc.

discover units  →  assemble a context bundle  →  agent authors prose  →  validate  →  human merges  →  stamp

Each step has one job:

• Discover enumerates the documentable units in a source, reading the repo's own declarations rather than guessing from folder names.
• Assemble (alloy generate) builds a deterministic context bundle for one unit: the exact source files a rule pack selects, the extraction prompts, the required sections, the template.
• Author is the agent's job. It reads the bundle and writes prose the bundle supports, marking anything it cannot verify with a ⚠️ GAP rather than guessing.
• Validate (alloy validate) runs the eight-validator gate. A doc that fails cannot merge.
• Merge is the human's job, always. Curation does not automate.
• Stamp (alloy stamp) writes provenance - and only after the gate passes, never at generation time.

The load-bearing property: which files matter is decided deterministically; only the prose is probabilistic. Everything an agent could get wrong mechanically - which files feed a doc, which sections are required, what frontmatter exists - is pre-decided in the bundle. Everything requiring judgment - distilling a concept, writing an anti-pattern - is left to the agent. Then a human merges.

The feedback loop

Right to left: the world tells the corpus where it is wrong.

source commits  →  per-unit drift  →  regenerate the affected units
agent queries that resolve to nothing  →  a measured coverage-gap queue

• Drift flows back from source. When a source commit changes files a doc was built from, that doc is mechanically marked stale (see Provenance and drift). Not on a timer - on the actual files.
• Gaps flow back from consumers. Every query an agent makes that resolves to nothing is recorded (the key and outcome, never session content) and surfaced as a ranked backlog. What agents look for and do not find is the corpus's highest-value work.

Nothing in the middle rots silently, because both directions are instrumented.

The one sanctioned exception

The daily pipeline never calls an LLM. The single exception is onboarding: alloy survey uses an agent to draft config (never content) for a repo Alloy has never seen, for human review. Setup is agent-powered once; the ongoing loop stays deterministic. That is the whole reason the tutorial starts with a survey and only then runs the deterministic loop.

The automation ladder stops at merge

Automation goes exactly two rungs and stops:

Rung	Who	What
Detect	automatic, continuous	drift and coverage reported daily
Propose	automatic, batched	regenerate, agent drafts scoped to changed files, one PR per unit
Merge	human, always	curation does not automate

The human rung is permanent, and it is load-bearing rather than cautious: unreviewed generated context measurably degrades agent performance, which is the whole reason the gate and the human sit where they do.