An auditable AI software-development system architecture

An AI development system earns the word *auditable* when a stranger can reconstruct any landed change from records alone: what was asked, what ran, what was proven, who admitted it, and how to go back. Teams usually discover they lack the property the first time an agent-made change breaks something and the best available evidence is a terminal nobody can reopen. Logging harder does not fix that, because a transcript is a view of execution, not a record of state — the moment an agent's work crosses from attempt into shared history is a transition, and if no machinery wrote that transition down, the system has stopped owning the fact of it.

This page turns that observation into a reference architecture for platform teams, built from three structures. Audit points are the transitions that must write evidence as they happen. Admission boundaries are the gates through which mutation of shared state is the only permitted passage. Rollback seams are the places the system can retreat without destroying what it learned while advancing. The worked implementation is YYLO — the three packages whose division of labor has its own definition — and every quoted contract below is verbatim from those packages' committed READMEs, seven from the control plane's README and one from the Benchmark package's, checked on 2026-08-29.

Auditability is a property of transitions

An AI development system is a state machine with agents inside it. Work crosses a short list of transitions — intent recorded, implementation isolated, agent run, validation proven, evaluation compared, admission decided, history written — and each crossing is the last moment the system holds both sides of it in one place. After the crossing, anything not written down has to be reconstructed, and reconstruction is where audits die. The architecture therefore assigns every transition exactly one record writer, and the writer is machinery, not the agent whose work is crossing:

intent ──▶ isolated checkout ──▶ agent run ──▶ validation ──▶ evaluation ──▶ admission ──▶ landing
task        base recorded          run           receipts       plans          queue        commit
record                              artifacts

Three invariants keep such records trustworthy rather than merely present. Evidence is written at the transition itself: a fact not captured while the crossing happens is a fact the system has given up owning. Evidence binds to bytes — trees, digests, exit results — because a summary can be produced by the very process that failed, and prose is not proof. And absence is a refusal: when a record a crossing requires is missing, the crossing stops visibly instead of completing silently. A system that treats missing evidence as a blank to backfill later has chosen reconstruction over audit, whatever its logging volume says.

Audit points: each transition writes its evidence

Walk the transitions of a governed change and name the record each one owns. The list below is YYLO's; the transferable part is the shape — every transition, one writer, one artifact.

• Intent recorded. The prompt is written down as a task record before anything runs, so later questions about what was asked read the record instead of the conversation. Records outlive their work: "Each task is isolated; exact get transparently resolves hot or archived state" — an audit does not depend on the task still being active, or on anyone remembering where it went.
• Implementation isolated. Dispatch hands the change a dedicated checkout and records the base it must land against, which turns concurrent agents into independent lines of work instead of interleaved edits. The worktree mechanics have their own treatment in this program; the audit point is narrower — the isolation itself is recorded, so a reviewer can name the exact base a change grew from.
• Agent run. Execution writes run artifacts as it goes, and reusability waits for persistence: "A successful step becomes reusable only after stdout, stderr, response, optional capture, and every declared receipt are atomically persisted and hash-bound with command/run/attempt identity." A crash therefore leaves either verified evidence or a visible hole — never a trustworthy maybe.
• Validation proven. Receipts carry the proof, bound to the exact tree that produced it: "Its readiness receipt binds the unchanged source tree, exact commands, exit results, measured outputs, log digests, and canonical evidence hashes; absent, failed, duplicate, stale, mismatched, or altered evidence fails closed." The half after the semicolon is the audit contract in miniature — evidence is checked against staleness, duplication, and alteration, not believed because it exists.
• Evaluation compared. Comparative questions get evidence designed to outlive any single session: immutable plans, isolated attempts, retained results. Even the spend is admitted against the plan — "Live run requires a juno_benchmark_task_authorization.v1 grant whose plan, models, currency, expiry, aggregate ceiling, and per-attempt ceiling exactly match the immutable plan." — so an evaluation's cost stays as reproducible as its outcome.
• Landing recorded. The queue's own record and the landing commit close the chain forward; the gate in front of that commit is structural enough to own a section.

The rule to take into your own system: enumerate the transitions, assign each one writer, and refuse the crossing when the write fails. A transition without a writer is an unauditable seam waiting for its first incident.

Admission boundaries: gates that own mutation

In an unauditable system the finish of an agent session is treated as the arrival of a change — nothing stands between the two to be checked. The architectural move is to split completion from landing, then serialize the landing. The gates stack from cheap to expensive, and each one refuses something specific.

• Validation selection is mechanical and fails toward more. Policy decides what a change owes before anything runs: "Inert configured text produces an exact zero-command proof, active product documentation runs only the cheap identity/link/schema/coherence audit, and mixed or unknown paths fall back." Read the final clause as the safety property it is — when the changed paths are mixed or unknown, the system falls back to broader validation rather than narrowing to a guess. An admission gate that cannot explain why a change was validated lightly is not a gate.
• A read-only report precedes the guarded write. Before the expensive half of admission runs, an inspection surface names the closure defects still standing on the candidate, so they get repaired while diagnosis is cheap instead of after enforcement has already spent its budget. The station-by-station walk of these gates belongs to this program's lifecycle guide; the architectural point is only the ordering — observe first, mutate last.
• Landing is serialized and read back. One queue owns the target: "The merge queue solely owns moved-target composition, conflict preservation, affected validation, bounded risk evidence, expected-SHA CAS, deterministic target readback, and reachability-safe cleanup." Two audit properties sit inside that sentence. The landing is read back from the repository instead of assumed from the write, and cleanup removes a candidate's checkout only when it is clean and its work already sits inside the advanced target — the tidying after a landing is itself bounded, never a side door for unrecorded removal.
• Disagreement has a budget. Review follows a stated risk policy, and a candidate that cannot converge is stopped after a bounded repair and delta-review allowance rather than looping at the gate forever. The stop lands as a recorded terminal state; exhaustion is evidence too.

The pattern beneath all four: few gates, fixed order, and no refusal is silent — the report names what failed, and the stop is a recorded state. Mutation of shared state has exactly one front door, and the front door writes down who walked through it.

Rollback seams: retreat without amnesia

The third structure is the one teams design last and need first. A rollback seam is a place where going back is cheap, and the audit question it must answer is: after the retreat, what remains known? Order the seams cheapest first.

1. Discard the checkout. Implementation lives in a workspace dedicated to the change, so the cheapest retreat is deleting a directory — shared history was never touched. What survives the deletion: the task record, the run artifacts, the receipts. The attempt stays fully described even after none of its bytes do. 2. Invalidate the proof. When the target advances underneath a queued candidate, the candidate's evidence describes a tree the target has left behind, and the system's answer is revalidation against the new tip — never landing on stale proof. The seam protects the target; its price is bounded re-verification. 3. Stop at the budget. A candidate that cannot converge is stopped rather than retried forever, and the stop carries its review evidence with it. Retreating here costs one queue position, not the audit trail. 4. Interrupt and resume. Interruption preserves the work already verified and restarts from the first unverified step, and the interruption is appended as evidence rather than erased: "Existing artifacts remain immutable and doctor-readable." A killed run remains a legible run — which is what lets recovery be honest without being optimistic.

And the seam that closes the loop: removing a landed change is itself another change — another task, another pass through the same gates, another landing — so even undo extends the record instead of puncturing it. The traceability contract compresses the chain to one line: "Every task links to a git commit." A revert links to one too.

Audit it yourself, read-only

The acceptance test for this architecture: a stranger with repository access and no special privileges can reconstruct a landed change's story without mutating anything, without the sessions that did the work, and without trusting any participant's summary. Auditing YYLO runs through its ordinary read-only commands:

yy ledger get TASK_ID
yy task status TASK_ID
yy merge status
yy merge arbiter status
yy merge plan TASK_ID --json

The first command answers intent, dependencies, and recorded responses; the second reports lifecycle state; the last three expose queue state and the exact integration plan for a candidate — all documented, all non-mutating. If reconstructing a change in your system requires write access, a dashboard login, or the author at the keyboard, the audit layer is not finished. What each retained artifact inside a run contains — the manifest, the streams, the receipts — is the evidence side of this architecture, and it has its own dedicated page.

Reuse this reference

What to cite from this page is the architecture itself: transitions write their own evidence, mutation crosses explicit ordered gates that record their refusals, and retreat preserves what advancing learned. Methodology: the eight quoted contracts were read from the packages' committed READMEs on 2026-08-29; the structures around them originate on this page and carry the evidence date in their header as their version. Cite the stable URL for the architecture and cite the READMEs for the contracts themselves — naming the source is what makes a published reference correctable, and the quotes are exactly the part to re-derive when their sources change.

For the neighboring layers of the same system: the boundary blueprint for the software immediately around one model — orchestration, context, evidence, lifecycle, failure — is its own reference, and the division of labor between the three YYLO components was linked in the introduction. A platform team can lift the three structures from this page first, then borrow the worked contracts one seam at a time.