Skip to content

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

  1. Write the entry rules (nine fields, append-only). Checkpoint: one entry can be written from a real task.
  2. Emit an entry per task. Checkpoint: the actor and the rules fields are filled.
  3. Add the cross-check against gate records. Checkpoint: a planted mismatch is reported.
  4. 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.

  1. Two questions, two records โ€” the execution log answers obedience; the runtime trace answers calls.
  2. Nine fields, append-only, with the actor and the rules applied.
  3. A log that disagrees with the gates is worse than no log, and the disagreement is checkable.
  4. Provenance shifts review from keystrokes to intent and evidence.
  5. The evidence pack is the log plus the gates โ€” the client audit, assembled from the repository.