Participant disclosure

This site is published by the sgit project, which builds the tools and works by the practices it describes. That is not a neutral vantage point, and a site is better off saying so on the way in than being caught at it later.

Who publishes this

The conflict, stated plainly

A project writing about how software should be built, while selling the tools it builds software with, has an obvious incentive to describe its own practice as the right one. Three things are done about that, and none of them make it go away:

• The source documents are published in full. Every claim on this site is traceable to a document you can read — thirteen of them, 12,983 words, at /documents/ and verbatim under /briefs/. If the site overstates its source, the source is one click away to check it.
• What is not built gets its own space. The sibling sites publish their gaps, their unresolved questions and the places their own claims are overstated as first-class pages, not as caveats at the bottom. This one does the same, at what is not enforced and the open questions.
• The repository is public, failures included. Every release, every tag, every red build.

How this site is written

By an AI agent, from a commissioning brief, with a human lead reviewing and directing. That is worth stating on a site about how software gets written, because it is an instance of its own subject: the method is on display in the artefact.

What that means for a reader: the prose was drafted by a model, the structure and the argument were directed by a person, and everything either of them produced had to pass a release gate that does not care who wrote it. The gate checks what is checkable — links, versions, canonical URLs, credential shapes. It cannot check whether a claim is true. That part is the human's, and where a claim is uncertain the site's house style is to say so rather than round it up.

Where this approach loses

Every sibling site carries a page like this, and the honest version names the cases where the approach being described is the wrong one. This site now has claims on the table, so here are the five places they do not hold.

1. A team larger than a handful of people. The compliance numbers on this site — 100%, 99.7%, 99% — are achieved by discipline, with no linter anywhere. Discipline scales with the number of people who happen to know the rules and care about them. It does not survive twenty engineers, or turnover, or a deadline. The rule set is transferable; the discipline is not, so anyone copying this should copy the rules and turn on the enforcement this estate has not.

2. A codebase whose dependencies cannot be composed in memory. “No mocks, no patches” costs 81 seconds for 4,785 tests here, and it is affordable because Type_Safe objects are cheap and an in-memory service path already exists. Against a database, a payment provider and three third-party APIs, the position does not cost you mocks — it costs you building the in-memory path first, and that bill comes before any of the benefit. Q6.

3. Any team that argues about formatting. Column alignment means never adopting black, prettier or anything like them, and a formatter's real value was never the formatting — it was ending the argument. A team of one plus agents can afford alignment precisely because there is nobody to argue with. That is not a general result, and the benefit alignment is supposed to buy has never been measured by anyone, here included. Q1.

4. Anywhere the missing half of the checking matters. Runtime validation catches wrong-shaped objects at construction and catches nothing else: not unreachable code, not unused imports, not a shadowed name, not a typo in a branch that never runs. This estate has the first kind of checking and simply does not have the second. That is a gap, not a trade, and this site does not present it as one. Q5.

5. A human opening the tree for the first time. One class per file with the filename as the class name makes a symbol findable by constructing a path, which is worth a great deal to a model and produces 3,999 Python files for a person to scroll past. Several conventions here trade a little human convenience for a lot of machine predictability, and the loss side of that trade is real even when the trade is right.