Chapter 21: Version Control as the Substrate¶
Everything That Matters Is a Versioned File¶
The portfolio needs one place where its facts live; this chapter makes the repository that place, and the tag the boundary of a release.
1. The Repository Is the Unit of Governance¶
The three structures hold because they are versioned. A rule that lives in a repository can be diffed, reviewed, rolled back and attributed; the same rule in a console cannot be any of those things. That is not a style preference — it is the difference between governance and memory.
The portfolio chapter made the state a file. This chapter makes the history of that file the substrate: every change reviewable, every release a boundary, every author attributable.
🎯 What You'll Learn¶
- Declared versus generated: what must be a reviewable file, and what must never be
- Why provenance becomes a review input, not a footnote
- The release boundary: a tag, a signature, and what each actually proves
Declared and Generated¶
| Declared — must be a versioned file | Generated — must never be committed |
|---|---|
| rules, manifests, registries | build artefacts |
| policy, contracts, schemas | caches and indexes |
| migrations | derived state |
| the evidence pack | secrets |
The rule is one line: if it can be rebuilt, it is generated; if it must be reviewed, it is declared. A generated file committed by accident is a file that will be edited by hand once, diverge, and never be noticed.
✅ What to Check¶
- Name one generated file that is committed. That is the first path to classify.
- Name one declared fact that lives only in a console.
2. Conventions That Make History Readable¶
A history is legible when it follows a shape everyone can predict:
| Convention | Why it exists |
|---|---|
| short-lived branches, trunk-based | the change is small enough to review and revert |
| one logical change per commit | bisect finds the defect, not the batch |
| a subject that states the change | the log is readable without opening the diff |
| tags only at the release boundary | a tag means this shipped, not this was tested |
The tag is the release boundary, and it should be the only thing that means it. A tag created for convenience destroys the one signal an operator relies on.
Signatures. A signed commit proves the bytes came from the key that signed them. It does not prove the change is correct, reviewed, or intended. That distinction matters because a signature is often cited as if it did.
The Provenance Rule¶
An agent-authored commit carries the agent's identity, and its review is named:
Author: <agent identity>
Co-authored-by / provenance: <agent name and version>
Reviewed-by: <human who approved the change>
The point is not ceremony. It is that a reviewer can answer who wrote this, and who accepted it without reconstructing the session.
✅ What to Check¶
- Does a tag mean "shipped", or does it mean several things?
- Can you name the author and the reviewer for the last ten commits?
3. History as the First Diagnostic¶
log, blame, bisect. Each answers a different question:
| Command | The question | The discipline it needs |
|---|---|---|
log |
what changed, and in what order | a readable subject |
blame |
who last touched this line, and why | an attributable author |
bisect |
which change introduced the defect | one logical change per commit |
The archaeology rule: reconstruct why, not only what. A bisect that finds a commit still requires reading the message and the review to understand the intent — and an agent-authored commit that says only "update" leaves the archaeology unfinished.
✅ What to Check¶
- Run a bisect on a recent defect. Does it land on one change or a batch?
- Does the commit message state why, or only what?
4. The AI Delta¶
Provenance stops being a footnote and becomes a review input: an agent's commit is attributable to its identity, never a borrowed human one, and a signed tag becomes a human's signature on a commit an agent wrote.
History is also the agent's cheapest context — and its most dangerous, because a bisect it cannot read is a regression it cannot explain.
💰 Cost Check: an unattributable commit costs an afternoon of archaeology; a tag that means several things costs a release nobody can audit; a generated file committed by hand costs the divergence you find a month later. The conventions cost a file and a review habit.
flowchart LR
C["commit — attributable"] --> B["branch — short-lived"]
B --> T["tag — the release boundary"]
T --> S["signed, and reviewed"]
S --> A["auditable history"]
C -.->|"unattributable"| X["archaeology"]
What this shows: the chain from a commit to an auditable release — and the single broken link that costs the audit.
The Delegation Line¶
The agent writes commits, assembles the changelog and runs the bisect. The human signs the tag and reviews the provenance. The system refuses an unsigned tag, a generated file committed by hand, and a commit with no attributable author.
5. Build the Delivery¶
Deliverables¶
| Artefact | Shape | Where it lives |
|---|---|---|
| declared/generated table | two columns, every path classified | docs/repository.yaml |
| conventions | prefixes, subjects, when a tag may exist | CONTRIBUTING.md |
| provenance rule | how an agent commit is labelled and reviewed | the conventions file |
| release-boundary check | refuses an unsigned tag or a tag off the default branch | the gate |
Decisions¶
| Choice | Default | What changes if you choose otherwise |
|---|---|---|
| branching | trunk + short-lived | long-lived branches, and merges nobody can read |
| signing | tags, because the release boundary is what a consumer trusts | commits too, if the audit demands it |
| provenance | a trailer naming the agent | a diff with no author |
| tag meaning | this shipped | a tag that means whatever the last person meant |
✅ Gates¶
- A generated file committed by hand is refused by diff.
- A tag whose commit is unsigned (or off the default branch) is refused before publish.
- A commit without an attributable author is a finding.
Runbook¶
- Classify every path declared or generated. Checkpoint: no path is in both columns.
- Write the conventions file. Checkpoint: a tag's meaning is one line.
- Add the generated-file gate. Checkpoint: a planted generated file fails.
- Enable tag signing at the boundary. Checkpoint: an unsigned tag cannot publish.
- Rehearse a bisect on a real regression. Checkpoint: it lands on one change.
🎯 Proof¶
- A history where every change is attributable.
- A tag that names exactly what shipped.
- A bisect that finds a planted regression in one sitting.
6. 🔑 Chapter Summary¶
Everything that matters is a versioned file, and its history is the evidence.
- Declared or generated — if it can be rebuilt it is generated; if it must be reviewed it is declared.
- Conventions make history readable: short branches, one change per commit, a subject that states the change.
- The tag is the release boundary, and a signature proves authorship, not correctness.
- History is a diagnostic — log, blame, bisect — when the commits are small and attributable.
- The agent's commits are attributable; the human signs the tag.