2026-08-29 · Updated 2026-08-29 · 11 min read
Evidence architecture for agentic engineering
The artifact taxonomy that makes agent work provable after the fact — receipts that bind claims to bytes, manifests that vouch for collections, session records that outlive the terminal, and checkpoints that make interruption legible — together with the integrity, retention, and regrade semantics that keep each role trustworthy, quoted from YYLO's committed contracts.
By Juno AI INC · evidence · system-design · yylo
When an engineer has to prove what an agent did — to a reviewer months later, to an auditor, to a postmortem, or to a future model re-reading its own history — the terminal transcript is the first thing offered and the first thing that fails. Scrollback is a view of execution that dies with the pane; a session is a conversation, not a record; and a participant's summary is precisely the document a skeptical reader cannot accept, because the process that wrote it is the process under judgment. What survives is whatever the run wrote down as it happened, in forms built to be checked rather than believed. That layer, sitting beneath the tools and beside the logs, has a shape — and it has four load-bearing parts.
This page is the evidence companion to the auditable-system reference. That page assigns every transition a record writer and every mutation a gate; this one opens the run directory and asks what the artifacts themselves actually are. The taxonomy that follows — receipts, manifests, session records, checkpoints — was extracted from YYLO's committed contracts, and each quotation below was read from the packages' own text on this branch and re-checked on 2026-08-29. Two neighbors own the closest surrounding ground; both are hyperlinked below instead of being retold here: the task-level chain from recorded intent through response and validation to commit is walked end to end at the task grain, and the vocabulary that keeps a reported value honest — complete, partial, unavailable, not applicable, a genuine zero — is defined value by value. What remains here is the artifact grain, and three semantics — integrity, retention, regrade — that decide whether the artifacts stay trustworthy after time passes.
Four artifact roles, one writer rule
Name the roles first, because most teams that believe they have "logs" in fact have one undifferentiated stream doing four jobs badly. Each role answers a different audit question, and conflating them is how evidence goes missing:
A receipt answers *did this happen*. A manifest answers *what existed*. A session record answers *where do I continue*. A checkpoint answers *where exactly did it stop*. The four differ in lifetime, in writer, and in what may later read them — which is why a system that writes them as one undifferentiated stream inherits the weakest semantics of the four.
Across all of them sits a single rule, and it is the rule that separates evidence from testimony: the writer is machinery, writing at the moment of the event it describes. A record reconstructed afterward by a participant — however honestly — is a recollection. A record emitted by the runtime while the event crosses, bound to the bytes that made the event what it was, can be re-checked by a stranger who trusts no participant. Every quotation in the sections below is an instance of that rule operating in a shipped system; the transferable content is the shape, not the command names.
Receipts bind claims to bytes
The receipt is the atomic unit of proof. It is small on purpose: one event, named, with the bytes that resulted — an exit status, a digest of what the command produced, the identity of the run and attempt that produced it. Two properties make a receipt worth more than a log line. It is *bound*: the claim and the bytes travel together, so the claim cannot be separated from what it describes and replayed elsewhere. And it is *minimal*: a receipt that archives everything proves nothing efficiently and tempts its keepers to prune it later, which is how honest systems quietly become unauditable ones.
What hashing actually buys — and what it honestly does not — is stated by the control plane's own scripts contract in one sentence worth quoting whole: "This is local corroboration, not cryptographic or signature-based receipt authenticity." Read that as the integrity disclosure every receipts design owes its auditors. Hashes detect drift: "Generation and doctor receipts classify exact files separately from preserved customizations, bind both preserved actual and packaged-source hashes, and detect later drift." Hashes do not establish who authored the bytes or that the author was trustworthy. A receipt architecture that claims signature-grade guarantees from content hashes is overstating its own evidence; one that names corroboration as corroboration can be cited accurately.
The other half of receipt integrity is what happens when old receipts are re-read by a later process — a resume, an amendment. Here the contracts enumerate the ways evidence rots and refuse each of them by name: "Only receipt-path relocation is allowed; missing, tampered, ambiguous, added, removed, reassigned, or weakened evidence fails closed." That list is a design pattern in miniature. The reader of historical receipts cannot verify that the past was honest; it can only refuse, mechanically and specifically, every shape of dishonesty it can name — absence, alteration, duplication, substitution, dilution. A system that cannot enumerate how its own evidence can rot has not yet designed its reader.
Manifests make collections auditable
One receipt proves one event, but agent work arrives in sets: a workflow of steps, a fan-out of parallel tasks, an experiment of attempts across models. The manifest is the role that vouches for the set — an index naming which artifacts existed, where, under which digests, at a defined point in the run. Where a receipt is a witness to an event, a manifest is the join table that lets a stranger assemble a distributed run without trusting any participant's memory of how the parts fit.
The contracts give the role two concrete shapes. For fanned-out work split across capped panes and child sessions, the package's own rationale for handoff artifacts is stated directly: "manifests make multi-session handoff auditable" — and the durable side carries the payload with it, because "aggregation artifacts preserve final agent responses, session IDs, commits, and statuses." Note what that pairing buys: the *identity* of each unit of work (its response, its session, its commit, its status) survives in a structured artifact even though the interactive surfaces that produced it — panes, scrollback, consoles — are ephemeral by design. Review after the fact reads the aggregation, not the terminals.
A manifest earns trust the same way a receipt does, minus the event: it is written by machinery, it binds what it names, and it refuses to bless collections it cannot verify. The practical test for your own system is the reconstruction test: kill every interactive surface, then ask a colleague with repository access alone to list what the run produced and what each artifact claims. If they can, the manifest role is filled. If they need a survivor's memory, the run is still testimony.
Session records outlive the terminal
Agent sessions are the identity that continuation and handoff depend on — resume, fork, follow-up — and identity is only useful if it can be found after the process that held it is gone. The session record is the smallest role and the most often improvised badly: a session identifier, retained in a durable artifact, deliberately separated from the mutable state around it.
The separation is the design decision, and the workflow contract states it exactly: "Durable run artifacts retain selected session IDs even though mutable history, branch, and runtime-marker files stay outside product worktrees." Two retention choices sit in that sentence, and both are load-bearing. Selected session identifiers are *kept*, in artifacts designed to outlive the run, so a later yy continue or cc continuation has something real to point at. And the mutable half of a session — history files, branch pointers, runtime markers — is *excluded from product trees* on purpose, because state that legitimately changes would make the durable half lie. The tmux handoff contract adds the per-task form: "each task keeps its scrollback plus per-task JSON result containing the session ID and final response" — the pane a human may inspect, and the structured record a program may read, kept for different lifetimes.
The broader practice of resuming, cloning, and handing off sessions has a dedicated page of its own in this program; the rule that belongs to the evidence layer is narrower. Identity outlives the terminal only if some machinery wrote it somewhere the terminal cannot delete. Every other property — continuation flags, clone scopes, registries — is machinery on top of that one retained fact.
Checkpoints make interruption legible
Long agent runs are interrupted; that is not an exception but a scheduled event, and the checkpoint is the role that makes interruption cheap. A checkpoint is an index of state written *before* failure can occur — the workflow contract is explicit about timing: "The first attempt writes run_contract.json, the single checkpoint and attempt index." The first attempt, not the failing one. Recovery is then a read, and the read is the strictest evidence consumer in the system: "recovery refuses active, partial, non-contiguous, cross-run, or drifted evidence, appends an interrupted manifest, and never infers semantic completion."
Three properties in that contract deserve separation. Refusal is the default: recovery trusts only evidence whose provenance it can verify, and every way a partially completed run can lie — still active, half-written, out of order, from another run, changed since writing — is a named refusal. Interruption is *appended*, not overwritten: the recovery event itself becomes evidence, so the run's history includes the fact that it was interrupted. And completion is never inferred: a step that stopped mid-flight is recorded as stopped, because a system that generously rounds an interrupted step up to success has converted its checkpoint from evidence into optimism. The one-line prohibition behind all of it is the no-backfill rule for the whole layer: "Never edit a historical run to make evidence reusable."
Retention cuts both ways
Retention is usually discussed as what to keep; for agent evidence, the must-never-keep half is equally structural. The benchmark launcher contract states the negative half with unusual completeness — for the secret and the prompt crossing a trusted boundary, "neither appears in argv, candidate environment, HOME/XDG, snapshots, or receipts" — and the boundary actively rejects laundering attempts: "Raw, hexadecimal, base64, base64url, URL-encoded, and JSON-serialized secret output or prompt content is rejected rather than retained." An evidence layer is a security boundary in reverse: everything retained becomes readable by every future auditor, so the set of retained bytes must be safe for that entire audience by construction.
The positive half of retention is equally deliberate. Keep the bytes that claims are bound to, under digests; keep the identifiers that continuation needs; keep the manifests that join them; keep refusal records and interruption records, because they are evidence too. Keep mutable runtime state out of durable stores, and keep secrets out entirely — the two exclusions point in different directions but share one justification: retained state that can silently change, or that must never be exposed, corrupts the durable half by association. A retention policy that cannot name both lists — what must survive, what must never survive — has not been written yet; it is only a storage bill.
Regrade means new readers, never new runs
Evidence that cannot be re-read under new judgment is evidence with a shelf life shorter than any grading standard. The regrade semantic keeps frozen bytes and changes the reader: a new grader, a new criterion, a new model judges the *retained* artifacts, and the operation is forbidden from producing new work. This is not an aspiration in the shipped system but a tested control — the release gate's positive controls include "regrading retained evidence without candidate execution," a real run re-graded with the candidate's call count provably unmoved.
Two rules keep a regrade honest. First, provenance of the thing being re-read: "governed rejudge over retained candidate truth that fails closed unless the caller supplies the original receipt_hash from a trusted immutable ledger (never from the mutable receipt being rejudged)." The rejudge must be pointed at the immutable original, proven by hash from a trusted store — not at a mutable copy that could already have been altered. Second, append-only generations: each new grading event appends a generation with its own grader identity rather than replacing the old verdict, so the question "what did we conclude then, and under which judge?" always has an answer. The step-by-step operator procedure for a governed regrade has a separate page in this program; what travels from it is the pair above — prove the frozen source, append the new reader, and never let judgment masquerade as execution.
Cite this evidence architecture
What is citable from this page is the taxonomy and its three semantics: four artifact roles — receipt, manifest, session record, checkpoint — each written by machinery at the moment of the event it describes; integrity as named-refusal corroboration rather than claimed authenticity; retention as two explicit lists; regrade as new readers over proven frozen bytes. Methodology: each of the fourteen quoted spans was read from the committed README text of the control-plane and Benchmark packages on 2026-08-29, whitespace-normalized and matched against the source bytes; the taxonomy, the writer rule, and the section structure originate on this page, and the evidence date in the header is this reference's version. Point citations at this page's stable URL for the taxonomy, and at the packages' own text for each contract — a citable artifact names what it rests on so others can correct it, and when the READMEs move, the quotations are the first thing to re-check.