Evidence Thinking and Audit Readiness

Why this matters

Mr. Hale visits Bramble Books once a year. He does not ask whether Shelf works. He picks one change and asks for proof. This year he picks CR-102, the gift card refund feature, and asks three questions: who approved the feature, what proves the tests ran before it merged, and where is the log of refunds over $200? Omar opens the repository. The PR shows Priya as the approver. The CI run attached to the PR shows make test with exit code 0 and a timestamp. The decision log at .gates/log.jsonl shows every refund gate decision with an approver. Four minutes, three files, done. Last year the same three questions took a week of scrolling through chat history, and one was never answered. This lesson is about the difference.

1. The build can succeed and the audit can fail

"It works" and "we can prove it" are two different claims. A green build tells you the code passed its checks at one moment on one machine. An audit asks a different question: can you show, later, to someone who was not there, that the right checks ran and the right person accepted the result?

Evidence is an artifact that answers that question without anyone's memory. It exists as a file, it carries a date, and someone who did not create it can find it.

Before you let Quill work on more of Shelf, ask four questions about every gate you have built. They are the spine of this lesson.

2. Control: which rule does this gate satisfy, and who owns it?

A control is a rule an organisation has already agreed to follow, with a named owner. Controls exist before your gates do. Bramble handles stored value (gift cards) and personal data (customer emails), so it already has rules about both, and Priya owns them. Your gates are not new rules. They are the mechanism that makes an existing control hold when an agent is doing the typing.

The mapping tells the auditor which rule to check the gate against, and tells you who to ask when the gate needs to change.

Write the mapping down in spec.md, in the evidence section you learned in L2. One line per gate is enough.

## 6. Evidence

| Gate | Control it satisfies | Owner |
|---|---|---|
| Refund over $200 pauses for approval | Dual approval for stored-value changes | Priya |
| Manager role only on refund endpoint | Least privilege for payments actions | Priya |
| make test passes before merge | Change control: tests precede release | Omar |

3. Evidence: what proves the gate ran, and where does it live?

Each gate produces an artifact when it runs. Your job is to know which artifact, where it lands, and who can reach it. Could Mr. Hale find it without asking you? Three kinds of evidence carry most of the weight in Shelf.

The decision log is the append-only file at .gates/log.jsonl that gate.sh writes every time a hook allows, asks, or blocks. From L4, each line holds a timestamp, the actor, the action, the verdict, the rule, and the approver when there is one.

{"ts":"2026-09-14T15:42:07Z","actor":"quill","action":"refund gift card GC-7781 $340","verdict":"ask","rule":"refund-over-200","approver":"priya","approved_at":"2026-09-14T15:49:31Z","pr":214}

The timestamped run is a CI run record. From L6, every run of make test and of the eval suite is stored with its commit, its model id, its config hash, and the time it ran. The URL of the run is attached to the PR.

The PR approval is the platform's own record of who clicked approve and when. That person is the reviewer of record: the human who accepted the change at the last stage boundary.

Where evidence lives matters as much as what it is. A log on Omar's laptop is not evidence, because Omar could edit it and nobody could tell. Evidence lives where no single engineer controls it: the CI system, the repository history, or a shared bucket that only CI writes to.

4. Metric: is the gate working over time?

A gate that ran once proves one thing. An auditor, and a team lead, want to know whether the gate keeps working. That needs numbers over time, and L6 gave you two kinds.

A leading indicator moves before the outcome you care about. For Bramble, the leading indicators are the eval pass rate over time and the time from a production incident to a permanent eval case. A lagging indicator records the outcome after the fact: how many regressions were caught in CI compared to how many were found in production.

The metric answers the auditor's follow-up: "Does the gate catch anything?" Six regressions caught in CI last quarter is an answer. "We think so" is not.

5. Cost: what does the gate cost, and can everyone see it?

Every human gate has a wait time cost: the minutes between the moment the hook returns ask and the moment a person answers. A gate that is expensive and invisible gets skipped, and a skipped gate is worse than no gate, because the spec still claims it exists.

The rule from L4 was to make the cost visible per gate. The decision log already holds what you need: the time the gate asked and the time the approver answered.

6. Enforced every time × evidenced automatically

Here is the definition that holds the lesson together. Audit readiness is the state in which any change can be proven compliant on demand. It is the product of two factors:

audit readiness = enforced every time × evidenced automatically

Enforced every time means the gate runs on every change, with no way around it. A gate in CI that blocks the merge scores high. A checklist people are asked to follow scores low.

Evidenced automatically means the proof is produced by the gate itself, as a side effect of running, not assembled by hand afterwards. A CI run record scores high. A screenshot someone remembers to take scores low.

It is a product, not a sum, because either factor at zero makes the whole thing zero. Added together, a gate that always ran but left no proof would score half marks. To an auditor it scores nothing.

7. The evidence pack for one change

An auditable change is a merged change that carries its own proof: the code, the evidence that the gate ran, and the name of the person who accepted it. The evidence pack is the list of artifacts that make one change auditable. For Shelf, the pack has one item per link of the artifact chain from L1.

Read the pack against the four questions. Control: the spec's evidence section. Evidence: the log lines and run records. Metric: the pass rate and threshold. Cost: the ask and approval times in the log. The workflow you already run answers all four.

8. Talking to an auditor

Mr. Hale asks the same four questions you asked yourself in section 1, about a change he chose, months after it merged, and he accepts only files. Three habits make the conversation short.

Answer with a file, not a description. "We always run the tests" is a description. "Here is run 5581, exit 0, 15

Name the person and the time. Every artifact in the chain has an author, a timestamp, and a reviewer of record. When Mr. Hale asks who approved this, the answer is a name and a date from the artifact, not "the team".

Show the control, then the gate, then the evidence, in that order. Skipping the control makes the gate look arbitrary. Skipping the evidence makes the gate look hypothetical.

Summary

• A green build proves the code passed a check once. Evidence proves, to someone who was not there, that the right check ran and a named person accepted the result.
• Ask four questions of every gate before scaling: which control it satisfies and who owns it, what artifact proves it ran and where it lives, what metric shows it works over time, and what it costs the people who wait.
• Evidence lives outside any one engineer's control: the decision log at .gates/log.jsonl, the timestamped CI run, and the PR approval by the reviewer of record.
• Audit readiness equals enforced every time multiplied by evidenced automatically. A gate that can be skipped, or one that leaves no artifact, scores zero.
• The evidence pack for one change is the artifact chain itself: intent, spec, plan, test log, eval run, decision log, and the approved PR. Answer an auditor with files, not memories.