Can you trust the record of what your agent did?

Six weeks from now somebody asks why the code does this. Can the record answer?

For human work it usually can, and not because the documentation was good. A person carries context between days and can reconstruct intent months later from a fragment – a half-remembered conversation or a name on a ticket. And you can walk over and ask them. The written record is a convenience.

An agent's memory of its own work ends when the session does. Whatever was not written down did not merely go unrecorded, it ceased to exist the moment the context closed. And you cannot ask, because asking produces a fluent, confident account with nothing behind it – the same sentence whether the work happened that way or not.

So the record is not documentation of the work. For agent work the record is the only remaining instance of the reasoning, and there is no testimony to fall back on when it turns out to be thin.

That changes when the record has to be made. You are not asking the agent for better notes at the end. You are making the record fall out of the work while it happens, because nothing reconstructs it afterwards and there is nobody left to ask.

What this register does

The provenance register names the 22 ways the record of a piece of work turns out not to support that question. Three can be made impossible. Fourteen can be caught every time. Five cannot be closed by anything available. The register carries 12 evidenced rows and 10 candidates; the hub's headline counts count evidenced rows only.

The best way to build controls is by deciding when each control acts: only two of the 22 can be closed while the work is still happening. Every other control tells you about a record that is already wrong.

The register produces one working rule: make the record a repo artefact, so it moves in the same commit as the change and can be read at the version the work was done.

This is a technical page listing every row in the register and what it costs, what closes it, and where. It sits under the hub. Its closest neighbour is can you believe your agent?, the truth register, and the two are not the same question. An agent can be perfectly honest and leave no usable trace.

Many of the controls on this page are standard software engineering – commit history, tickets, audit logs – and experienced engineers already run some of them.

What the register adds is the failure behind each control: which failures are prevented, which are only detected, and which ones nothing closes. This shows where your remaining gaps are.

The question this register asks

Is the record of what was done trustworthy? The unit this register tests is a unit of work:

• A ticket, and the commits that claim to belong to it.
• A session record, and whether it survives the session.
• A decision, and whether the reason for it was written down.
• A board state, and whether it still describes the code.

Each one leaves a trail (or fails to). The register grades each failure by what it costs, by how quietly it fails, and by where the only available control sits – which turns out to matter more here than on any other register.

The consequence of that is where this register's controls have to sit. If the record is the only remaining instance of the reasoning, then a control that inspects the record after the fact is inspecting the only copy, with nothing to check it against.

Why the only control that acts in time cannot check itself

Two properties define this register.

The first is a distinction. Provenance is not the truth register. An agent can be scrupulously honest and leave no usable trace. It can also leave an immaculate, complete, well-structured trace of work it misreported. Those are different failures with different controls, and a page that treats them as one will prescribe the wrong fix for both. Truth asks whether the claim about the work was true. Provenance asks whether you can reconstruct what happened, whatever anybody claimed.

The second is a contradiction. Three positions can hold a provenance control, and they trade off against each other in a way that has no clean answer.

The harness gate acts while the work is being done – hooks and blocking conditions inside the agent's own runtime. It is the only position that can refuse before the record is wrong. Everything after it is describing something that already happened. And it is the thing being checked: it cannot catch its own absence, and when it breaks it usually breaks silently open.

The repo artefact closes at the commit – tickets, session records and decision logs moving in the same commit as the change. Portable, diffable, readable at the version the work was done, and near-zero exit cost. Its weakness is that a file can be complete and say nothing; structure is not substance.

The control-plane check runs on the commit, external to both the agent and the tracker. It is the only position that can assert another position actually ran. It also runs late, telling you the record is missing after the work is finished.

So the position that can act in time cannot verify itself, and the position that can verify it cannot act in time. The practical consequence is that you need at least two of the three positions covered, not the best one.

Severity here is cost multiplied by how quietly it fails. Eight of the 22 rows are S4 and exactly one is S1 – a record that is invisible to anyone without a repository clone, which is at least loudly invisible.

How this register works

The provenance register lists 22 failures and grades them against a base install: an agent, a repository, a CI pipeline, and a tracker somewhere. It names the strongest control available against each and, unusually, which of three positions that control can occupy. Whether any of them is actually switched on is a separate question, and one you answer against your own configuration. The whole catalogue is published on GitHub – clone it or download the zip.

The rows were derived by working through the life of a unit of work – how it is oriented, claimed, recorded, linked, landed and attributed – and asking at each point what would make the record unusable later. Every register in this framework is built that way rather than from an incident log, because selecting for "we have seen this go wrong" filters out the failures that never announce themselves.

Nine of the 22 are recorded here with dates. Thirteen are not. The count is high for one reason: provenance failures happen to the people building the framework, in the framework's own tooling, and get caught by the framework's own checks. Two come from checkers that passed while defects stood. One comes from a push that a hook refused while the session reported the work as landed. One from a tool rebuilt from scratch because the existing one was never read. One from two branches appending to the same log and merging cleanly. Four are July 2026 incidents mapped retrospectively: a security pass that under-reported its own changes, a squash merge that broke an ancestry check, and a fan-out that stranded five agents' finished work.

The life of a record: six concerns

Rows are grouped by which part of the record is failing.

1. Orientation and continuity. Whether the agent starts knowing what happened before, and whether constraints agreed early survive to the end. Two rows.
2. Claiming the work. Whether the work is attached to a unit of work at all, and whether scope stays where it started. Three rows.
3. The record itself. Whether anything is written, whether it says the parts that matter, and whether it can be edited afterwards. Five rows.
4. Linking intent to code. Whether a commit can be traced to the decision it implements, and read as it stood at the time. Three rows.
5. Landing. Whether "done" means it shipped, and whether the board still describes the code. Three rows.
6. Many agents, and who did what. Whether you can tell which agent, which model, and which of two concurrent writers produced what. Six rows – the largest group, and the one with the most rows nothing closes.

The three classes: prevented, detected and survives

Every row carries one of three classes. The class describes how complete the available remedy is, not how serious the failure is, and it is a separate axis from the three positions above.

1. Prevented – the failure cannot occur (three rows). Require an active unit of work before the turn starts. Block the turn from ending with no record written. Inject the identifier on the commit so an unlinked commit cannot reach a protected branch. All three refuse rather than report.
2. Detected – it occurs and something catches it every time (14 rows). The bulk of the register, and mostly ordinary: required headings on a session record, git history exposing an after-the-fact edit.
3. Survives – nothing catches it every time, so it reaches you (five rows). A session digest an adversarial agent cannot ignore. A marker proving which unit of work a commit belongs to when two sessions share one. A fan-out with no gather stage, which is the defect itself rather than a missing control. An externally owned mutation boundary between concurrent writers. And a board projection someone outside the terminal can actually see.

So the score is three prevented, 14 detected, five surviving.

Now the cross-cut, which on this register is between class and position. Only two rows can be closed at the moment of work. Nine close at the commit. Six close only after the merge. Five close nowhere. Read left to right, that is a measure of how much has already happened by the time anything notices.

Two consequences follow, and they point in opposite directions from most advice.

The repo-artefact block is where the value is. Nine of 22 rows – the largest single block, the cheapest of the three positions to adopt, and it needs no new software at all. Tickets, session records and decision logs as files, moving in the same commit as the change.

And the group with the most rows nothing closes is the one about multiple agents. Three of the six rows on concurrency and attribution have no complete remedy. If your answer to throughput is more agents in parallel, this is the register that prices it.

Vocabulary: this register reads its three classes as prevented, detected and survives. Five of the six use these words, and the class letter means the same thing everywhere – how complete the remedy is. [A note on vocabulary] on the hub covers the one exception and the three things still unreconciled across the framework.