How it Works

It started as a coordination kernel. It has become the loop around it: capture → rate → plan → preflight → execute → gate → land → record — with the execution layer driving headless agents through build→review turns under hard verification gates, and the operations layer carrying everything an unattended run needs around that.

Layer 1 — the tick kernel

tick coordinates agents through a shared local event log under .tick/events/:

• Path-scoped claims. Agents claim work by path; overlapping claims are serialized by an O_EXCL lock, so two agents can't quietly edit the same file.
• Projection, not state. A projection folds the append-only event log into .tick/STATE.md — the coordination state is always derivable from the log.
• Local transport only. No per-event push/fetch, no remote dependency, no server — one shared .tick/ directory per active run.

The kernel is deliberately tiny and test-covered: bin/tick, src/, test/ in the repo, and install.sh can materialize it into any other repo.

Layer 2 — the execution layer

relay-automation/ runs agents headlessly in turns: a Producer builds an artifact, a Reviewer critiques and proposes fixes, and the loop hands off through files — a relay thread plus the artifact under review — until it converges. The Reviewer's STATUS: line drives the loop: approved/closed is terminal, anything else is another round, bounded by a round cap.

Every turn runs inside a shared containment core (relay-automation/relay-turn-lib.sh):

• a path allowlist per turn, tightened further for reviewer turns;
• worktree isolation by default under the driver — the agent writes to a throwaway worktree and only allowlisted files are copied back;
• a commit-bypass guard that resets the repo if an agent commits mid-turn;
• a wall-clock watchdog and typed exit codes, so a timeout is never mistaken for a defect;
• no pushes, ever, from a turn shim.

Layer 3 — the operations layer

Execution alone doesn't survive contact with an unattended run. Work that is under-specified, colliding, ungated, or unrecorded fails for boring reasons, so each failure mode got a durable surface — and the stages compose into one loop:

• Issue-first intake. A GH issue becomes a capture doc and a parked row in the release ledger — work is written down before anyone asks an agent to do it.
• A scored backlog. pri / sev / appeal / effort ratings decide what runs next.
• A wave planner. Exact write-set intersection, zone caps, and dependency gating decide which lanes can run together without colliding.
• Preflight. Freshness probes, already-landed detection, and a readiness verdict — is this specified well enough to run while you sleep?
• Verification gates. A gate must be able to start before turn 1, and gates run under CPU, wall-clock, and RSS caps; a killed gate exits distinctly so a runaway is never triaged as a defect.
• A release ledger. SQLite plus a git-mergeable SQL dump with receipted writes — what did we promise, and what shipped with evidence?
• PDDA doc governance. Frontmatter, status tables, and ledger coverage keep the doc tree resumable by an agent tomorrow; drift between docs and code is a defect.
• HQ. Multi-repo resolution with capability tiers and previewed writes — the operator front door across every repo on the machine.

Two design commitments hold the layer together: machine-readable boundaries (state crossing a subsystem boundary travels as a schema-stamped JSON artifact, never parsed out of logs or prose) and deterministic before advisory (regex, schema, and file checks may block; LLM review may warn, rank, or propose but never block).

Marathon — chaining relays unattended

A marathon chains several build→review phases from a MARATHON.yaml plan:

• Strictly sequential phases. One at a time, in plan order. depends_on validates the order you authored; it does not create a parallel execution graph (see the FAQ).
• A gate at every boundary. Each phase's verification gate must be able to start before turn 1 — a missing gate fails fast instead of being skipped. Gates run under wall-clock, CPU, and memory caps, and a killed gate is recorded distinctly from a failing one.
• Typed escalation. Failures halt the chain and land in ESCALATION.md with reason codes — the run tells you what went wrong instead of retrying blindly.
• Recovery is read-only. After a crash or reboot, marathon-recover.sh reports which commits are ungated so you can re-run the gate or revert before trusting them.

Where concurrency actually lives

Phases inside one plan are serial on purpose. Real parallelism exists across runners and sessions:

• Swarms — separate agents in separate full clones or worktrees on disjoint write-sets, coordinated by tick locks.
• Interactive sessions — multiple live agent sessions in one shared workspace coordinate their claims through the same .tick/events/ log.
• Triage fan-out — read-only subagents inspect backlog items in parallel while each lane's execution stays sequential.

The execution model in one ladder

Quality assurance & verification architecture: two-tier review

XYZ Forge treats code and repository quality as a top priority. Quality assurance is divided into two decoupled tiers so that fine-grained code correctness and macro system delivery are both rigorously verified:

• Tier 1 — Per-issue code-level QA (Builder ↔ Reviewer relay): Detailed code analysis is performed for every individual GitHub issue or marathon phase. A distinct Reviewer agent (separated from the Builder model) reviews modified files in full (swept file: yes), validates acceptance probes, and must emit an explicit Approved status. The harness then runs real test suites (validate.sh) and generates a machine-checkable on-disk gate receipt (.xyz/receipts/<SHA>.json).
• Tier 2 — Final branch PR & orchestrator framework checks: When closing out a marathon branch or landing a jog queue, the main orchestrator model acts as the outer supervisor performing a mechanical framework system check rather than a superficial second-pass diff read. Deterministic tooling (marathon-closeout.sh, gate_receipt.py, githooks/pre-push) hard-locks the base branch against main, verifies on-disk gate receipts for the final commit SHA, confirms CI attestation, and validates that diff sizes match the task scope before merging.

How “done” is defined

XYZ separates a claim from evidence: an uncommitted run artifact is not proof. Gates are real commands that must pass on the final state; a passing assertion counts only once it has been seen to fail on a mutated input; and every phase boundary, escalation, and approval is recorded as events you can audit after the fact.