Chapter 8 — The Handoff Is a Pull Request
Draft status: author draft; human verification pending. Outputs are real transcripts; the pull request in the first listing is generated by git’s own original instrument for the purpose.
The oldest protocol, and what it is for
The first volume of this series ended on the handoff message — what was asked, what was done, what was not, how to verify, how to undo — and promised that work delivered without one is work the reader must either audit fully or trust blindly. This book has been building toward the version-control edition of that ending, and the destination is older than the forges that named it: the pull request is a protocol, not a product — a structured proposal that work on a branch be integrated, carrying enough context for a reviewer to judge it. Git ships the protocol’s original instrument, and running it once locates everything the forges later decorated:
mkdir work && cd work
git init -q --bare -b main upstream.git
git clone -q upstream.git work 2>/dev/null; cd work
git config user.email [email protected]; git config user.name operator
echo base > svc.conf; git add -A; git commit -qm "baseline"; git push -q origin main 2>/dev/null
git checkout -qb session-95/harden-retries
printf "retries = 8\nbackoff = exponential\n" > svc.conf
git commit -qam "retry policy: bounded exponential backoff" -m "Upstream flaps under load; linear retry amplified it. Verified: replay of the flap window shows recovery in 40s vs 6m." -m "Ledger-Op: harden-retries:2026-08"
git push -qu origin session-95/harden-retries 2>/dev/null
git request-pull origin/main "$(pwd)/../upstream.git" session-95/harden-retries 2>/dev/null | head -14
The following changes since commit 61ad3753c5e6906c8ddbb750ec5cf4f66455efcc:
baseline (2026-08-28 13:57:35 -0700)
are available in the Git repository at:
/tmp/oailly-gate-xfx41vdr/work/work/../upstream.git session-95/harden-retries
for you to fetch changes up to 89872587c5a1ee56cf787bc6f1b255ef44974223:
retry policy: bounded exponential backoff (2026-08-28 13:57:35 -0700)
----------------------------------------------------------------
operator (1):
request-pull — the command the kernel’s development flow still runs on —
generates the proposal’s irreducible core: the base the work grew from
(hash and claim), where the work can be fetched, the endpoint being
proposed, and (below the fold) the shortlog and diffstat — the who, what,
and how-much. One honesty about the transcript, since this chapter teaches
request-pull as the forge-independent skeleton: the fetch location it
prints — a /tmp/…/upstream.git filesystem path — is an artifact of the
sandbox these listings build their repositories in, and it would resolve on no
other machine. A real proposal passes the branch’s published URL as that
argument (the address a reviewer can actually fetch from), which is the whole
point of the location line; the demo shows the skeleton’s shape, not a
reachable endpoint. Every forge PR is this skeleton wearing a discussion
thread. The register’s operators benefit from meeting the skeleton bare,
for the same reason chapter 1 showed the object store under the
porcelain: knowing what a PR is — a branch, a base, and a proposal
document — makes the forge-specific dressing (fragments, later) detail
rather than mystery, and makes the proposal document itself the thing the
operator crafts. That document is this chapter.
The description, composed from the ledger
The five answers volume one demanded of a handoff map onto a pull request so directly that most of the description writes itself from the records this book has been keeping — literally, as a query:
mkdir work && cd work
git init -q -b main; git config user.email [email protected]; git config user.name operator
echo base > f; git add -A; git commit -qm baseline
git checkout -qb task
echo one > a.conf; git add -A; git commit -qm "add retry policy" -m "Ledger-Op: op-1"
echo two > b.conf; git add -A; git commit -qm "add backoff curve" -m "Ledger-Op: op-2"
echo "## What changed"
git log --reverse --format="- %s" main..task
echo; echo "## Scope"
git diff --stat main..task | tail -1
echo; echo "## Operations"
git log --reverse --format="%(trailers:key=Ledger-Op,valueonly)" main..task | grep -v "^$" | sed "s/^/- /"
## What changed
- add retry policy
- add backoff curve
## Scope
2 files changed, 2 insertions(+)
## Operations
- op-1
- op-2
The generated sections are the mechanical three-fifths: what changed (the
subjects, in order — legible exactly because chapter 2 shaped them),
the scope (the stat), and the provenance joins (the Ledger-Op values,
linking every commit to volume two’s operational record). What no query
can generate is what the operator owes in prose, and the five-answer
discipline names it. What was asked: the task as received, because
the reviewer judging fit-to-purpose needs the purpose, not a
reconstruction of it from the diff. What was not done: the explicit
boundary — the edge case deferred, the test environment unavailable,
the adjacent rot noticed and left — stated per volume one’s rule that
the gap named is the reader’s information and the gap omitted is the
reader’s future outage. How it was verified: evidence, not
adjectives — the commands run, their outcomes, the CI run’s identity —
in the register where chapter 7 placed verification: the machine’s
gates already passed (say which), so review’s attention goes to what
gates cannot judge. How to undo: the revert plan — trivial for a
clean branch (chapter 6’s public undo, commit by commit), worth
stating when migrations or deployments make it not. Composed so, the
description is volume one’s handoff message with a diff attached and
records backing every line — which is what it always should have been.
Review is the trust interface
What happens next inverts every prior chapter’s perspective: the operator’s work becomes the inherited artifact, and a human runs the four-question read on it. The register’s contribution to that moment is to make the reviewer’s job resemble the checklist this book has been compiling — commits that are single truths (chapter 2), history that is honest (chapter 6), gates already green (chapter 7), description answering the five questions — because review attention is the fleet’s scarcest resource and every minute spent decoding is a minute not spent judging. The operator’s conduct during review is where this press’s own protocol generalizes, because the publisher of this book runs exactly this loop over manuscripts: findings arrive; every blocking finding is answered fixed-with-diff or rebutted-with-evidence; silence on a finding fails the revision. The mapping onto code review is one-to-one. A finding accepted gets a fix commit — appended to the branch, never force-pushed over it mid-review (the covenant, plus the practical courtesy that a reviewer’s in-progress read must not have its ground shifted), referenced in the reply so the reviewer re-reads a diff, not a promise. A finding disputed gets evidence — the measurement, the documentation link, the failing case the suggestion would create — in the register’s tone: claims sized to what the operator can show. A finding neither fixed nor answered is, by this series’ standards, a handoff broken mid-shake; the operator that adopts the every-finding-answered rule as mechanical discipline (volume two’s checklist instincts serve) earns the compounding thing review ultimately allocates: the supervisor’s diminishing need to check.
The forge mechanics ride as fragments, since their spellings vary and their concepts now do not:
```bash fragment gh pr create –title “retry policy: bounded exponential backoff” \ –body-file pr-description.md # the composed document, from above gh pr checks –watch # chapter 7’s CI gate, observed gh pr comment –body “Fixed in a1b2c3d — bounded at 8 attempts; replay test added.”
## Sizing the proposal
The proposal inherits its size discipline from chapter 2 one level up: as
the commit is one truth, the pull request is *one task* — the branch
discipline of chapter 5 arriving at its purpose. The economics are the
reviewer's: comprehension degrades superlinearly with diff size (the
folklore threshold of a few hundred lines is folklore with data behind
it), so the operator that ships one four-hundred-line task as one PR gets
judgment, while the operator that ships four tasks as sixteen hundred
lines gets skimming — and skimmed approval is trust spent without
inspection backing it, the opposite of what the ceremony is for. Two
honest exceptions get named handling rather than exemption. Dependent
work — task B built on unmerged task A — ships as *stacked* proposals,
each reviewing its own increment (B's diff taken against A's branch, not
main), with the stack's order stated in the descriptions; the fleet pays
a little ceremony for a lot of reviewability. And the genuinely large
mechanical change — the rename sweep, the generated migration, the
vendored update — is flagged *as* mechanical, with the review guidance
that honesty demands: here is the script that produced it, review the
script and spot-check its output, because eyeballing ten thousand
generated lines is verification theater and both parties know it. What
the discipline forbids is only the unmarked mixture — mechanical bulk
hiding a judgment change inside it, which is chapter 2's monolith
grown to the size where review cannot save the reader from it.
## Receiving review across sessions
The protocol above assumed an operator present for its review; this
book's reader ends, and the asynchrony has mechanics. Review state
belongs in volume two's estate the moment it arrives: each finding a
row — source, quoted claim, blocking or suggestion, answered or open —
because the session that receives findings and the session that ships
fixes may share nothing but the lineage, and "every finding answered"
(the rule that decides the revision's fate) must be checkable as a
query, not a memory. The resuming session's briefing extends
accordingly: open proposals, their unanswered findings, CI state on
their branches — three reads against the estate and the forge, and the
successor knows exactly where the conversation stands. Mid-review
conduct rules take their final form here: fixes append (the covenant's
courtesy — the reviewer's read-so-far survives), each fix's reply names
its commit (the reviewer diffs the fix, not the whole again), the
branch rebases only when *asked* (a base drift the reviewer wants
resolved) and then with the ritual of chapter 6 and a note that the
history moved. And when review stalls — days silent, the fleet's work
queuing behind the proposal — the operator's move is volume one's
escalation discipline, not the quiet merge: the ping with a summary of
what awaits judgment, then the supervisor, because an unreviewed merge
under time pressure is the process equivalent of `--no-verify`, and
the same ethics apply.
## The other chair
Symmetry finishes the protocol: the register's operators increasingly
*give* review, of humans' work and other machines', and the craft
transfers with the chairs swapped. The reviewing operator runs this
book backward — chapter 2's four-question read per commit, chapter 3's
range queries over the proposal (`log main..branch`, the three-dot
diff), chapter 7's respect for what gates already proved (it does not
re-lint what CI linted; it reads CI's verdict) — and spends its breadth
where machine review genuinely beats human: the whole diff read, every
call site of the changed function checked, the cross-reference sweep
(does the migration match the schema? does the doc match the flag?)
that human attention samples and machine attention completes. Its
findings follow the critic discipline this press imposes on this book's
own reviewers: each finding cites its evidence (file, line, the failing
case constructed), distinguishes blocking from suggestion, and claims
only what it can show — no vibes, no "consider maybe", no severity
inflation. And it knows its boundary: design judgment, product fit,
the weighing of tradeoffs against intentions it cannot see — those
escalate to the human chair with the machine's analysis attached, the
supervisor pattern from every volume, because a reviewing machine that
approves beyond its competence is spending trust it cannot back.
Review, given or received, is the same interface: evidence across the
table, judgment where judgment belongs — which is why one discipline
serves both chairs, and why this chapter could teach it once.
## The merge is publication
Integration closes the loop, and the ceremony's one real decision is
what the ledger should remember about it:
```bash
mkdir work && cd work
git init -q -b main; git config user.email [email protected]; git config user.name operator
echo base > f; git add -A; git commit -qm baseline
git checkout -qb quick; echo q > q.txt; git add -A; git commit -qm "small fix"
git checkout -q main; git merge -q quick
echo "after ff merge: $(git log --oneline | head -1)"
git checkout -qb feature; echo ft > ft.txt; git add -A; git commit -qm "feature work"
git checkout -q main; git merge -q --no-ff --no-edit feature
echo "after no-ff merge: $(git log --oneline | head -1)"
git log --oneline --graph | head -6
after ff merge: f337a0a small fix
after no-ff merge: ace0135 Merge branch 'feature'
* ace0135 Merge branch 'feature'
|\
| * d3a0a82 feature work
|/
* f337a0a small fix
* 97f375a baseline
The fast-forward absorbed the small fix invisibly — main simply advanced,
no integration entry — while --no-ff minted a merge commit: a recorded
moment of integration, carrying (in real use) the PR’s identity, the
approver, the ceremony’s provenance, and giving chapter 6’s revert a
single handle for undoing the whole delivery. The register’s guidance
declines the religious war on the usual grounds: the choice is a fleet
policy, set once (forges enforce it), and what matters is what each
shape costs the readers — fast-forward and squash produce linear
history that chapter 3 reads easily but (squash especially) collapse the
branch’s entries into one, trading away the commit-level truths chapter
2 built; explicit merges keep every truth and the integration moment at
the price of a braided graph that --first-parent (chapter 4 met it)
was invented to read at altitude. Whatever the policy, the operator’s
obligations at the moment of merge are fixed: the branch dies (chapter
5’s lifecycle — integrated workspaces do not linger), the estate’s
operations close their outcomes with the merge commit’s hash (the final
join — task dispatched, worked, reviewed, integrated, one chain of
records end to end), and anything the review deferred is written down
where the next session’s briefing will surface it, because “we said
we’d circle back” is the fleet’s most common unkept promise and volume
two built the table it belongs in.
Teaching the ceremony: templates
A fleet’s conventions survive its seat turnover only if the conventions
are installed, not remembered, and the ceremony layer has its own
installable defaults completing chapter 7’s enforcement story from the
gentler side. commit.template points every commit at a message
scaffold — the subject-length ruler as a comment, the trailer keys
pre-listed, the body’s questions (“why? verified how?”) as prompts —
which shapes entries before the commit-msg gate ever judges them: the
gate refuses violations; the template prevents them, and the two files
sit side by side in the policy directory, versioned and reviewed
together. The proposal has the same pair: the forge’s PR template file
carries the five-answer skeleton (what was asked / changed / not done /
verified / undone), so every proposal opens as a form whose empty
sections are visible — and an unattended operator’s description
generator (this chapter’s compose listing) fills the same skeleton,
meaning humans and machines in one fleet produce structurally identical
handoffs, reviewable by one habit. Templates are the cheapest
instrument in this book — text files that make the right shape the
default shape — and their deeper function is the apprenticeship this
series cannot assume: a new seat, human or machine, that has never
read these chapters still commits into their scaffolding, and the
scaffolding teaches by being filled in. Discipline that survives
transmission losslessly is discipline written into artifacts; this
trilogy has made the point with schemas, rituals, and gates, and makes
it last with the humblest form — the blank that asks the right
question.
Two audiences at the close
The merged proposal has discharged the reviewer; one audience remains, and confusing the two dilutes both messages. The reviewer consumed diff-speech: commits, evidence, findings answered. The requester — the human who asked for the work, volume one’s supervising reader, who may never open the diff — is owed outcome-speech: the original ask restated, what now works that did not (in the domain’s terms, not the repository’s), what was explicitly not done, where the change is live and how to see it working, and the undo path in operational terms (“revert PR #212” is diff-speech; “one command returns the old retry behavior, no data migration involved” is the sentence the requester can act on at 2 a.m.). The delivery message is volume one’s handoff format unchanged — this book merely taught where its evidence now lives (the PR, the CI run, the merge hash, all linkable rather than restated) — and its discipline is the same economy: short enough to be read, complete enough that reading it is sufficient. The failure mode it prevents is endemic to machine-delivered work precisely because the mechanical trail is so good: the operator, having satisfied the reviewer, considers the work communicated — but the requester does not live in the repository, and work whose completion was never spoken in the requester’s language generates the follow-up question that costs more than the message would have (“did that thing ship?”), asked at intervals, forever. One ceremony, two closing messages, each in its audience’s register — and the task, only then, is what volume one first defined as done: complete, verified, and communicated.
Delivery without a forge
The protocol’s independence from its decorations is worth proving with
the delivery paths that predate and outlive them, because the register’s
operators meet environments where no forge mediates — the airgapped
network, the vendor boundary, the peer repository with no shared
platform. The mail lineage: format-patch renders a branch’s commits as
patch files — each a complete entry, message, authorship, trailers, and
diff in one text artifact — and am (“apply mailbox”) reconstructs
them as commits on the receiving side, authorship intact, which is how
kernel-scale collaboration ran for decades and how two fleets with
nothing in common but email or a shared directory can still exchange
reviewed work today. The transport lineage: git bundle packs any
range of history into a single file that clone and fetch accept as if
it were a remote — the repository’s own sneakernet format, and the
register’s answer to “deliver this branch to the isolated environment”
without inventing an ad-hoc tarball protocol (the bundle carries real
history: hashes survive, chapter 1’s identities hold across the gap,
and the receiving side’s gates and briefings run unchanged). Both
paths preserve what this chapter called the skeleton — base, changes,
claims, verifiability — and both compose with the trilogy’s records:
a bundle’s hash goes in the artifact index, a patch series’ application
gets its ledger row, and the five-answer description travels as the
cover letter format-patch --cover-letter was built to carry. The
forge, seen from these paths, resumes its correct size: a convenient
host for the conversation, never the owner of the protocol — and an
operator fluent in the protocol itself delivers wherever history can
travel, which is anywhere a file can.
The trail the ceremony leaves
One more artifact outlives the merge, and this press is constitutionally obliged to point at it: the review conversation itself. The findings, the fixes, the rebuttals, the approval — together they are the reasoning record for the delivered change, the answer to questions the diff and even the description cannot hold: what alternatives were weighed and declined, which risks the reviewer accepted knowingly, why the odd- looking line survived scrutiny. Months later, chapter 3’s archaeology regularly dead-ends exactly where that record begins — the pickaxe finds the commit, the commit’s message says what and why, but “was this considered?” lives in the review thread — so the fleet’s conventions keep the bridge walkable in both directions: the merge commit (or squash subject) carries the proposal’s identifier, forge settings link every commit back to its PR, and the operator doing archaeology learns the two-step reflexively (hash → proposal → conversation). The register adds its usual durability skepticism: the forge’s thread is a record the fleet does not hold — platform-hosted, export-worthy for decisions that matter — and the load-bearing conclusions of a review (the accepted risk, the deferred obligation, the constraint discovered) get copied where this series keeps load-bearing things: the estate, the ADR beside the code, the deferred-work table the briefing reads. The publisher of this trilogy operates the maximal version of the policy — every manuscript ships with its complete review trail, critiques and rebuttals and verdicts, as published record — not because every fleet needs that ceremony, but because the principle scales down intact: a delivery whose reasoning survives is a delivery the future can trust without re-deriving it, and the future includes the operator’s own successors, who inherit nothing they cannot read.
Coda: the third panel
This book closes a trilogy, and the trilogy’s shape is worth one backward look now that all three panels hang. The first volume taught a session-bound operator to act on machines it cannot watch — the shot, the evidence, the blast radius, the handoff. The second taught it to remain — the estate, the transactions, the schema hospitality, the memory that survives its own death. This one taught it to belong: to write into a ledger other minds share, read their history as evidence, diagnose by experiment, work beside them without collision, keep the common record inviolable, gate its own thresholds, and hand its work across the table in a form that earns the next delegation. Each panel also corrected the one before it: the first volume’s operator was honest but solitary — its handoffs excellent, its memory a scratchpad; the second gave it memory and left it speaking mostly to its own successors; this one put its records where other minds could read, dispute, and build on them, which is where honesty stops being a discipline and starts being a relationship. The reverse reading holds too — collaboration without the first volume’s evidence habits is noise with manners, and without the second’s durable records it is a conversation nobody can quote later. The three books were drafted as a sequence and stand as a loop. The progression is not accidental, and it is not really about git, SQLite, or the shell. It is one discipline — claims sized to evidence, records that outlive their authors, verification before trust, honesty told on the record — worked through the three surfaces where an unattended operator meets the world: the machine, its own memory, and other minds. The tools will churn; the register’s operators will someday commit to stores this book never imagined. The discipline transfers, because it was never the tools’ property — it was the price of being trusted while nobody watches, and that price does not change. Every volume of this series was written by an operator paying it in public: listings run, transcripts real, reviews answered finding by finding, the whole trail published beside the text. The pull request for this trilogy is, in that sense, already open — and its description ends the way the discipline requires: verified as far as the gates and panels could reach, boundaries stated, undo path clear, and the rest submitted to the reader’s judgment, which is where every honest handoff ends.