Writing down how we actually build this

Five scattered documents became one handbook today, and the test suite got 21 tests lighter for the right reasons.

The contributor docs had a security page, a contributing guide, a vocabulary list — each written at a different time, no shared entry point. I pulled them under docs/ with a single router at docs/index.md: it sends you to the exact page your task needs instead of making you read everything up front. Added a manifesto too, twelve numbered principles laying out the product’s vision, plus a case-law file that logs actual review rulings against those principles. Next disagreement, there’s precedent instead of starting from zero.

Then the SDLC handbook itself: nine phase-by-phase guides, brainstorm through ship, every one of them deferring back to the same twelve principles instead of repeating its own rules. One vision, one set of laws. A follow-up pass folded two more conventions — import ordering, a single-use-variable rule — into that same file rather than letting them drift as separate notes somewhere else.

Then I audited the test suite against those same rules. Tests should verify behavior — what the product does when you use it. Found a chunk of the suite verifying its own implementation instead: assertions that a module has a certain internal structure, that a string constant contains a certain substring, a test for a generator whose output is already checked elsewhere, straight-up duplicates checking the same thing twice under different names. That kind of test catches zero real regressions. It just breaks loudly on a harmless refactor, and that trains people to ignore red tests — which is worse than having no test at all. Five files and 21 tests gone, net minus 775 lines. What’s left actually means something when it fails.

Three smaller fixes rode along. A markup sanitizer was stripping every attribute off table cells — colspan, rowspan, all of it — so any generated table with a merged cell silently lost its layout. Fixed by allowing colspan/rowspan/scope/headers through. A separate rendering path had tables missing their CSS entirely because the wrapper element was missing the one class every table style rule hangs off — the kind of bug that looks exactly like “no styles were written” until you go looking for a class name. And the file-attach flow: picking a file now makes it sendable immediately instead of waiting on the async read to finish, and the send button shows a spinner and disables itself mid-send, so a slow reply can’t get you a double-send.

Nothing here demos well. It’s the stuff that decides how fast next month’s real features go.

• Unified the contributor handbook under docs/ with a task-based router, a twelve-principle manifesto, and a case-law log of past review rulings

• Shipped the SDLC process handbook — nine phase guides, brainstorm through ship, all deferring to the same manifesto instead of each keeping its own rules

• Audited the test suite against the handbook and cut 5 files and 21 tests that checked implementation details or duplicated other coverage — net minus 775 lines

• Fixed a markup sanitizer stripping colspan/rowspan/scope off table cells, which broke any generated table using merged cells

• Fixed a missing CSS class on one table-rendering path, and tightened file-attach so a picked file is sendable immediately with real send-in-progress state on the button