Justification travels in the diff

A rule belongs in the rules file. That is where it can be maintained, where the next person will look for it, and where it stops being scattered across a hundred places that each drift on their own schedule. Every instinct a well-organized repository trains points that way, and the instinct is right nearly always. It is wrong at exactly one moment, and that moment is the one where the rule was supposed to do its work.

The moment is review. Somebody approving a change does not read the repository. They read the change, a bounded set of removed and added lines, and they decide on the evidence inside that boundary. Whatever sits outside it is not evidence they have, however true it is and however carefully it was written. Our own boundary guard states the consequence without softening it. To widen the exposure of a document, an approval marker has to travel in the same file’s diff as the change it approves, and a marker committed in a sibling file, or already sitting elsewhere in a file this commit does not touch, approves nothing at all. The guard reads the diff, not the working tree.

The mechanism is that a justification held anywhere except inside the change is absent at the instant the decision is made, so the reviewer approves an unexplained edit while a perfectly good explanation sits somewhere else being correct and unread.

We did not set that down as a house rule and then apply it three times. It arrived three times, in different repositories, written by different hands against different problems, and none of the three cites either of the others. The boundary guard’s version governs disclosure. Our website repository carries a second version in its standing instructions for agents, which is that operator feedback becomes a dated ruling in the same commit as the fix, and that a change altering rendered appearance without updating that ledger is incomplete rather than merely undocumented. The design authority in the same repository carries a third, which is that a fix promoted into the shared foundation package moves as code, validator, registry entry, and canonical documentation in one change or does not move. Disclosure review, design authority, and package promotion share almost nothing except that each is a place where a decision has to survive being read later, by someone who was not there when it was made.

The oldest version of the rule is twenty years old and was written under legal pressure. When litigation over the origins of kernel code made contribution provenance a live question in 2004, Linux adopted the Developer Certificate of Origin, and the durable thing about it is where the certification goes. Not into a contributor register, not into a signed agreement filed with a foundation, but into the commit itself, as a Signed-off-by line attached to the change it certifies. This corpus has already argued the attribution half of that decision, that a shared structure needs every piece to carry its maker’s name. The placement half is the one at issue here, and it is why the practice still works across tens of thousands of contributors. The certificate cannot be separated from the code without deleting it.

What makes this urgent rather than tidy is who writes the changes now. An agent can produce a paragraph of justification on demand, and the cheapest place to put that paragraph is a document nobody diffs, where it will read beautifully and be consulted by no one. A reviewer facing forty machine-proposed changes before lunch will read forty diffs, and forty explanations filed elsewhere will go unread in a way that leaves no trace, because unread is not a state any system reports. Co-location is not a filing convention. It is the only arrangement in which a reason and the thing it justifies reach the same pair of eyes in the same breath, and a reason that arrives with its change is still working on the busiest morning of the year, when every policy nobody has time to open has quietly stopped.