Chapter 10: Execution Transparency¶
The Log Is the Evidence¶
1. Execution Transparency¶
A client asks how a change was reviewed six months ago. The thread is gone, the CI retention window closed in March, and the answer is a memory of a conversation.
Execution transparency is the discipline of making the work auditable without the tool that produced it. The execution log is the record that makes it possible. It is append-only, it lives in the repository, and it is written as the work happens: what was read, what was decided, what was changed, and which gates ran.
Prior chapters built the controls on the three structures โ routing, continuity, procedures, escalation, economy. Each of them leaves a claim about work already done, made by the party that did the work. This chapter builds the record that proves those controls ran. Without it, every claim a control leaves is a memory of a conversation.
The rule this chapter defends: a record that can be edited, or that lives only in a vendor's retention window, is not evidence.
๐ฐ Cost Check: an absent log costs a client audit assembled from memory, and a review that reconstructs authorship from diffs. A nine-field entry costs a minute per task. The expensive failure is not the missing entry today โ it is the release, six months from now, whose evidence nobody can reconstruct.
๐ฏ What You'll Learn¶
- Why the work needs its own log โ the four facts, the three properties, and where they must live
- The nine-field entry โ what each field proves, and why the entry is append-only
- The check that keeps the record honest โ the log's gate results must match the gates' own records
- What provenance does to review โ from reconstructing authorship to reading intent and evidence
โ What to Check¶
- Take the last change an agent made. Can you say what it read, from the repository alone?
- Which record answers "did the gate pass?" If the answer is a memory or a dashboard, the log is incomplete.
2. The Records Around It¶
Four mechanisms exist in the same estate, each answering a real question. None of them is the execution log, and each one relates to it:
| Mechanism | What it answers | Its limit |
|---|---|---|
| the platform's logs | what the software did: requests, errors, latency | the software's story, not the work's โ a decision is not an event in it |
| the runtime trace | what calls were made, in what order, with what timing | it proves the execution happened; it cannot show what was decided |
| the gate records | did this check pass, fail or block | the authority on that result; it shows the result, not the reason |
| the evidence pack | how do you know, for one release | it is assembled from the log and the gates, not a separate truth |
Read the middle column and the shape is visible: the platform logs and the trace record execution; the execution log records evidence; the gate records are the authority the evidence cites; the evidence pack is the evidence assembled for a reader.
When something goes wrong, two questions get asked. The first โ did the agent obey the Law? โ is about work, and the execution log answers it, because the answer must outlive the tool. The second โ what calls were actually made? โ is about execution, and the trace answers it, because that record is enormous and short-lived.
flowchart LR
W["work: reads ยท decisions ยท gates"] --> L["execution log<br/>survives the tool"]
E["execution: calls ยท timing"] --> T["runtime trace<br/>short-lived, enormous"]
L --> A["the audit<br/>= log + gate records"]
T -.->|"not the audit"| A
What this shows: the log and the trace answer different questions; only the log survives long enough to audit.
โ What to Check¶
- Does your estate record what the software did, and what the work did? If only the first, the log is missing.
- Where does the answer to "did this gate pass?" live โ a system with a retention window, or the repository?
3. The Log Entry¶
# one entry, append-only
timestamp: <when>
task: <what was being done>
files_read: [<paths>]
rules: [<law ids applied>]
decisions: [<what, why, rejected>]
gates: [{ id: <gate>, result: pass|fail|blocked }]
outcome: <what happened>
next: <the next action>
actor: <human | agent identity>
| Field | What it is for |
|---|---|
| timestamp | order; the only field a machine supplies |
| task | the unit of work, so entries can be grouped |
| files-read | the routing check โ what the routing table said to load, and what the run actually opened |
| rules | which Law ids were applied โ the difference between obeying and claiming |
| decisions | including what was rejected; the field a reviewer needs |
| gates | pass, fail or blocked, with an id |
| outcome | what actually happened, not what was intended |
| next | the resumption point |
| actor | the identity that acted โ an agent's, never a borrowed human's |
The economy chapter adds three cost columns to this entry โ tokens, retries, tier. They extend the nine; they do not replace them.
Append-only. An entry is never edited. A correction is a new entry that says so. The moment a log can be edited, it stops being evidence and becomes a narrative.
One Record, Four Scopes¶
Every control in this part writes into this record. The routing table's files-read proves what was loaded; the handoff artefact's
decisions are the entry's decisions; a procedure's gates appear as gate results; a blocked report is one entry with a condition and a
decision; the economy's spend columns extend the entry. They are not separate records โ they are the same append-only log, seen at four
scopes:
| Scope | The record | What it answers |
|---|---|---|
| one session | the handoff artefact | where was I, and what did I decide |
| one task | one log entry | what was read, decided, changed, gated |
| one gate | the gate's own record | did this check pass |
| one release | the evidence pack | how do you know |
Same fields, growing scope, one append-only record.
The outcome tells the truth. If a gate failed and the change shipped anyway, the outcome says so. A log that flatters the run is the one that cannot be trusted later.
โ What to Check¶
- Does every entry name the rules applied? Without that field, compliance is a claim.
- Can you find an entry whose outcome contradicts its gates? That is the entry worth auditing.
4. The Log and the Gates Must Agree¶
A log that disagrees with the gates is worse than no log.
If the log says a gate passed and the gate's own record says it failed, the log is not merely wrong โ it is a false alibi. The gate is the authority on its own result; the log is the authority on what was attempted.
The check is mechanical: for each gate result in the log, the gate's own record must confirm it. A mismatch is a finding, and it means one of the two records is lying โ usually the log, because it was written by the party with an interest in the outcome.
The Cross-Check¶
for each log entry:
for each gate result in the entry:
assert the gate's own record has the same result at the same commit
a mismatch is a finding, not a formatting error
โ What to Check¶
- Is anything cross-checking the log against the gate records? If not, the log's gate field is a claim.
- Take one entry and verify two gate results by hand.
5. Provenance, and What Review Becomes¶
Provenance is the actor field, done seriously: the identity that wrote each change, the AI model or version where relevant, and the review that approved it. For agent-authored work, provenance is what allows a reviewer to focus on intent and evidence rather than tracking who typed what.
A review that must reconstruct authorship is a review that reads diffs without context. A review that has provenance, the decisions and the gate results focuses on the one question that matters: is this the right change?
What a Client Audit Looks Like¶
The log plus the gates is the evidence pack: what was attempted, what was decided, what was verified, and who signed. That is a defensible answer, and it is assembled from the repository rather than from memory.
One entry, as the answer to "how do you know?":
timestamp 2026-11-06 14:20
task change the retry policy on the checkout worker
files-read contracts/queue.md ยท runbooks/retry-policy.md ยท services/checkout/worker.tf
rules law:no-secrets ยท law:test-accompaniment
decisions cap retries at 3 (rejected: 5, because the queue's visibility timeout is 30s)
gates schema-validator pass ยท integration pass ยท policy-check pass
outcome merged; deploy gated to Tuesday's window
next await the Tuesday window
actor agent:checkout-worker ยท approved by the-orchestrator
Six months later, that is the difference between a review and an archaeology project: the constraint is named, the rejected option is recorded, the gates are attributable, and the actor is a person or an agent โ never a borrowed identity. That is a defensible answer, and it is assembled from the repository rather than from memory.
โ What to Check¶
- Can you name the actor for every change in the last release?
- Does a reviewer get the decisions and the gates alongside the diff?
6. Build the Log¶
Artefacts¶
| Artefact | What it is for | Where it lives |
|---|---|---|
| execution log | append-only entries, nine fields | docs/log/<period>.md or a machine log |
| entry rules | the nine fields, and the append-only rule | the Playbook |
| cross-check | log gates vs gate records | the nightly audit |
| evidence pack | the log plus the gates for a release | the release pack (Part Four) |
Decisions¶
| Choice | Default | What changes if you choose otherwise |
|---|---|---|
| log format | one entry per task, nine fields | unstructured notes that cannot be audited |
| editing | append-only; corrections are new entries | a narrative that flatters the run |
| authority on a gate | the gate's own record | the log's memory of it |
| provenance | an actor per entry, agent identities included | a diff with no attributable author |
โ Checks¶
- Every entry has nine fields, including rules and gates.
- The log's gate results match the gate records; a mismatch is a finding.
- No entry is ever edited; corrections are new entries.
Sequence¶
- Write the entry rules (nine fields, append-only). Checkpoint: one entry can be written from a real task.
- Emit an entry per task. Checkpoint: the actor and the rules fields are filled.
- Add the cross-check against gate records. Checkpoint: a planted mismatch is reported.
- Assemble one evidence pack from the log and the gates. Checkpoint: it answers "how do you know?" without a meeting.
Done When¶
- The log answers what was read, decided, changed and gated for any task.
- A mismatch between the log and a gate is caught, not discovered later.
- A release's evidence pack can be assembled from the repository.
7. ๐ Chapter Summary¶
Transparency is a record that can be audited without the tool that produced it.
- Two questions, two records โ the execution log answers obedience; the runtime trace answers calls.
- Nine fields, append-only, with the actor and the rules applied.
- A log that disagrees with the gates is worse than no log, and the disagreement is checkable.
- Provenance shifts review from keystrokes to intent and evidence.
- The evidence pack is the log plus the gates โ the client audit, assembled from the repository.