Onboarding

This section is the fluency layer. It teaches the advanced topics gateline depends on but never explains, the things a competent senior engineer has usually had no occasion to learn. It teaches each of them through the specific place in this codebase where it does real work.

The other three sections answer different questions. CONTRIBUTING.md is policy: whether you can contribute and how a fix gets routed. How It Works is concepts: what the design is and why it holds together. Reference and the API pages are exact shapes: flags, fields, schemas, symbols. None of them covers the background knowledge those documents take for granted. That gap is what these modules fill.

The audience is senior and above: engineers who can already read the codebase but who have not previously needed git's object model, a compare-and-swap write loop, or a grammar strict enough for a parser to bounce. Beginner git material is deliberately absent: cloning, committing, branching, and pushing are assumed. Each module opens with the general concept, then walks the concrete anchors in the repository, then offers a short set of questions you should be able to answer without looking anything up.

Modules 1 and 2 carry runnable exercises. Have a terminal and a throwaway git repository open before you start them; module 3 reads fine away from a keyboard.

Modules

1

Git, down to the plumbingExercises

Objects, refs, and refspecs; update-ref and compare-and-swap; fast-forward-only as a policy primitive; reading a file without checking its branch out; worktrees; and commit messages as a protocol, and the limit of that idea.

2

The co-written state fileExercises

The state file as a document rather than a serialization; compare-and-swap write loops, refusal, and re-derivation; actions that stay idempotent because they derive from committed state; append-only ledgers and derived totals.

3

Contracts and their parsers

The ID and heading grammars; the READABILITY rule family and how it varies per contract; bouncing a malformed artifact instead of guessing at it; where the parsers live, which shapes have none, and how to evolve a contract without breaking them.