Everyone agrees an audit trail is a good idea. Far fewer agree on what has to be in one before it earns the name. This is the specification we work from, and the reasoning behind each part.
The unit is an event, not a session
Sessions are too coarse. An agent working for forty minutes across nine files produces one session and nine very different stories. The useful unit is the event: one prompt, one response, one set of file changes, bound together.
What each event must carry
Time, in UTC. Local timestamps across a distributed team produce sequences nobody can reconcile.
Identity. Which machine and which user account the event came from. Without it you have activity, not attribution.
Tool and version. Which agent ran. Tools behave differently and change behaviour between releases.
Model and version, where available. Some tools expose this and some do not. Where it is unavailable the field must be empty rather than inferred — a guessed model name in an audit record is worse than a blank one.
Project and file path. The repository and the specific file touched.
Change magnitude. Lines added and removed, so contribution can be measured without re-parsing diffs.
Redaction state. Whether secret-stripping applied, so a gap in the stored text has an explanation.
Integrity: append-only and chained
An audit trail that supports editing is a database. Events should be added and never modified in place; a deletion should itself be an event, so the fact that something was removed survives the removal.
Chaining gives you tamper evidence. Each event's hash is computed over its canonical contents plus the hash of the previous event, starting from a genesis record. Altering an entry changes its hash, which breaks every link after it. That does not prevent tampering — nothing stored on a machine somebody controls can — but it makes tampering visible, which is the property that matters when the record is challenged.
Verification should be a command with an exit code, not a screen somebody has to read. If a pipeline can fail on a broken chain, the chain gets checked continuously instead of annually.
Honesty: the part most tools skip
An audit trail has to distinguish between what it knows and what it does not. Three rules follow from that.
Unmeasured is not zero. If a figure was not produced, the report leaves it blank with an explanation rather than defaulting it.
Unattributed is its own category. Lines that cannot be matched to an interaction are reported as unknown, never folded into the human column.
Uncovered is not clean. A repository with no recorder running is listed as unmonitored. Silence must never be presented as a pass.
What it deliberately does not do
An audit trail does not judge code quality, block anybody's work by default, or certify compliance with anything. It records what happened accurately enough to be argued with. Everything useful downstream — reporting, policy, review evidence — is built on that and is worthless without it.