Architecture

Architecture

How the engine works under the hood. For the model, read Concepts first.

tron start / --watch ─▶ tron.py (deterministic)
                          │  the flow driver — walks workflow.toml phase by phase
                          │  dispatch — free slots ▶ ready blocks, cap = max_parallel
                          │  WAKE — the heartbeat: wakes on register work, idles otherwise
                          │  the LLM only to BUILD and for narrow typed judgments
                          ▼
                    advance ─▶ record (events.jsonl) ─▶ land / escalate

Two spines, one source

• Pass spine — engine/workflow.toml: the phases a block moves through (build → review → merge → wrap → landed), their gates, words, and transitions.
• Exception spine — workflow.ESCALATION (in engine/workflow.py): where a stuck or uninterpretable signal goes — architect-first, then operator.

engine/workflow.py parses and lints both, and generates docs/WORKFLOW.md; engine/bpmn.py generates the interactive workflow/ BPMN (pass spine + escalation overlay) from the same tables. The diagram cannot drift from the code because it is produced from the code.

The truth gate (engine/gate.py)

The gate never trusts a claim. For a >>DONE it derives the facts itself — commits exist, the trunk is untouched, the engine's own test run is green — and then challenges the worker to answer >>CONFIRMED with per-criterion evidence before DONE stands. Reviewers judge in their own detached checkout pinned to the engine-attested sha. The worker owns the merge inside a single engine-wide window (a MERGE lock); the engine performs the mechanical land (fast-forward the ref) and re-runs the suite on trunk.

The closed vocabulary (engine/glossary.py)

One dict is the single source for every legal word, its sender role, and its required fields; the parser and docs/GLOSSARY.md are generated from it. The engine reads exactly one >> line per reply and validates it against the sender's role — illegal or ambiguous replies route to the architect.

The typed event log (engine/events.py)

Every engine decision is one JSON line in the run's events.jsonl — a closed, generated vocabulary (docs/EVENTS.md). This is the single measurement source: run stats, the SIM harness, and any after-the-fact analysis read the events, never prose logs.

Prompts (engine/prompts/, engine/prompts.py)

Every boilerplate the engine says to an LLM is one file under prompts/; the loader composes shared parts ({gateway} gateway rules, {persona} personas). Nothing is defined twice.

Liveness — talk before you page

A worker that overruns is not killed on silence alone: the engine probes the session, re-issues once, and only then pages — talk-first. A crash at boot is recovered deterministically (stray processes killed, unverified branches preserved as orphan/*, blocks re-dispatched).

File layout

engine/     # the deterministic engine (Python) + workflow.toml + prompts/
docs/       # GENERATED reference: GLOSSARY.md · EVENTS.md · WORKFLOW.md; voice.md
workflow/   # GENERATED interactive BPMN diagram (vendored bpmn-js)
evaluation/ # the SIM validation suite: harness.py + templates/

Per-run, the engine writes a verbatim transcript, the typed events.jsonl, a manifest, a report, and the exact workflow.toml that drove the run.

See also: Concepts · Operations.