Sequence · concurrency control

A claim only counts after the control plane reads it back

Claim read-back sequence Two dispatchers race to claim one ticket. Dispatcher B wins, while Dispatcher A detects the remote assignee during read-back, aborts, and takes the next ticket. write assignee = A write assignee = B claim accepted read remote assignee assignee = B abort; take next ticket Dispatcher A competing worker Dispatcher B winning worker Control plane remote truth Ready queue next ticket

Venn comparison · path-scoped concurrency

Parallel work is safe only when owned path sets do not intersect

Owned Paths collision comparison Ticket A and Ticket B own disjoint paths and may run in parallel. Ticket C overlaps Ticket A's event-runtime scope and must wait. Disjoint · parallel Overlap · serialized Ticket A event-runtime/lib/ Ticket B site/src/content/docs/ Safe to run together intersection = ∅ Ticket A dispatch.mjs + test Ticket C event-runtime/lib/** COLLISION Ticket C waits strict policy blocks overlap

Flowchart · independent evidence

The exit code—not the agent report—decides whether work advances

Independent verification gate After an agent reports completion, a worker runs the exact verification command. Exit zero permits handoff; a non-zero exit retains evidence and routes the ticket through recovery. YES NO Agent reports completion commentary Worker runs exact command outside the agent process Exit code 0? falsifiable evidence Successful handoff advance to review Retain failure evidence output + receipt data Recovery policy retry · requeue · human hold

Structured artifact · ticket specification

Five explicit fields turn a request into dispatchable work

Agent-ready ticket structure A loose request is specified into one durable ticket containing problem context, acceptance criteria, source pointers, owned paths, and an exact verification command. clarify write INPUT Loose request intent, symptoms, partial context TRANSFORMATION Specify narrow scope make proof runnable DURABLE ARTIFACT Agent-ready ticket Todo · ai:agent-ready · unassigned Problem & Context what is wrong and why it matters Acceptance Criteria observable, falsifiable outcomes Source File Pointers where relevant behavior lives Owned Paths one path or glob per bullet Verification Command exact command runnable in worktree

Sequence · offline demo

The demo exercises the complete loop without external accounts

Offline demo sequence The Factory orchestrator creates an isolated worktree, dispatches the starter ticket, applies a deterministic patch, verifies it, opens and merges an in-memory pull request, and cleans up. create fixture dispatch DEMO-1 + paths apply patch run exact bun test exit 0 open + merge PR #1 clean up Orchestrator factory demo Worktree isolated fixture Harness deterministic Verify independent gate Forge in-memory PR

Process · repository onboarding

Five setup steps turn a repository into a dispatch target

First real pull request setup Initialize Factory, configure the project board, register the repository, file an agent-ready issue, and dispatch it to produce the first real pull request. 1 Initialize factory init factory doctor 2 Project board exact Status states protocol labels 3 Register repo base · paths · verify config/repos.yaml 4 Ready issue scope + criteria owned paths + proof 5 Dispatch claim → worktree verify → pull request

Architecture · pluggable harnesses

Factory owns the workflow; adapters translate it for each agent

Pluggable harness routing The Factory orchestrator sends one bounded run contract through an adapter registry to provider adapters or the deterministic fake adapter, keeping workflow policy independent of agent provider. run contract CONTROL Factory orchestrator claim · isolate · verify review · receipt ROUTER Adapter registry installed capabilities classic + event runtime Provider adapters Claude · Gemini / AGY Codex · Cursor · Pi provider-specific CLI translation TEST / DEMO Fake adapter deterministic simulator

Secure paved road · Gondolin

A worktree isolates processes; Gondolin isolates trust

Gondolin sandbox boundary Host-side policy sanitizes the child environment, mounts only the declared workspace into an ephemeral virtual machine, blocks secrets, and permits network egress only through an allow-list gate. Host boundary Ephemeral Linux VM sanitized command workspace only Adapter policy sanitized child environment mutating vs read-only rules Declared workspace filesystem provider bounded repository view Host secrets remain outside guest Guest command ephemeral VM process placeholders, not host secrets Workspace mount declared files only Egress gate default deny · allow-list blocked

Architecture · kernel and extensions

Packs describe work; only installed extensions execute new code

Kernel, pack, and extension boundary Explicit policy registration admits data-only packs and operator-installed executable extensions into the Factory kernel, which provides planning, execution, approval, artifact, and verification primitives. register data code EXPLICIT REGISTRY Policy config exact pack paths installed extensions FACTORY KERNEL Runtime primitives plan · approve · execute artifact · verify · receipt Data-only packs Definitions · prompts · schemas routes · edges · schedules never auto-discovered Operator-installed extensions Adapters · hooks · connectors executable capability explicit trust decision Workers · API · web UI one governed execution surface

Architecture · independent repository cells

One fleet policy supervises repositories without sharing their limits

Multi-repository fleet isolation A fleet controller routes work into independently configured repository cells. Each cell has its own control plane, base branch, verification command, worktree lifecycle, and concurrency ceiling. FLEET CONTROL Factory controller global default · per-repo override Client app · max 2 GitHub control plane base: develop Worktree pool repo-specific verify Factory repo · max 4 Linear control plane base: develop Worktree pool independent lifecycle Docs repo · max 1 GitHub control plane base: main Worktree pool own ports + database

Loop · infrastructure operations

An ops action closes only when a fresh observation verifies it

Infrastructure operations loop A monitoring event creates an isolated workspace, a data-only pack analyzes it, an operator-approved extension acts, a fresh observation verifies the result, and a receipt feeds the next event. Event monitoring signal Workspace versioned input Analyze data-only pack Approve & act installed extension Verify fresh observation Receipt evidence + outcome Versioned evidence input · decision · outcome