Writing down how we actually build this

Today was about the parts of a project that don’t show up in a changelog but decide how fast everything after them goes: the rules contributors actually follow, and whether the test suite tells the truth.

The contributor-facing docs had been growing the way docs always grow — a security page here, a contributing guide there, a vocabulary list somewhere else, each written at a different time with no shared entry point. Today they got pulled into one place under docs/, with a single router at docs/index.md that sends you to exactly the page your task needs instead of making you read everything up front. Alongside it: a manifesto laying out the product’s vision as twelve numbered principles, and a case-law file that logs actual review rulings against those principles so the next disagreement has precedent instead of starting from scratch. Then the SDLC handbook itself landed — nine phase-by-phase guides covering everything from brainstorming a feature to shipping it — each one deferring back to the same twelve principles rather than repeating its own rules. One vision, one set of laws, every process document pointing at the same source instead of drifting apart from it. A follow-up pass folded two more conventions (import-ordering and a single-use-variable rule) into the same file rather than letting them live as separate one-off notes.

The other half of the day was less pleasant and more necessary: a full audit of the test suite against those same handbook rules. Tests are supposed to verify behavior — what the product actually does when you use it. What the audit found was 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, tests for a generator script whose output is already checked elsewhere so testing the generator itself was redundant, and outright duplicates checking the same thing twice under different names. None of that catches a real regression — it just breaks loudly when someone refactors something harmless, which trains people to ignore failing tests. Five whole files and 21 individual tests came out, net minus 775 lines, and the suite that’s left is smaller and tells you something true when it goes red.

Three smaller fixes landed in the gaps around that work. A markup sanitizer was stripping every attribute off table cells, including colspan and rowspan — meaning any table Chalie generated with a merged cell silently lost its layout. A separate rendering path had tables missing their CSS entirely because the wrapper div was missing the one class every table style rule depends on — an easy miss, since the bug only shows up on one of two rendering routes and looks identical to “no styles were written” rather than “the class name is missing.” And the file-attach flow got tightened: picking a file now makes it available to send immediately instead of waiting on the async read to finish, and the send button now shows a spinner and disables itself mid-send so a slow reply doesn’t invite a double-send.

None of today is a feature you’d point to. It’s the plumbing that makes the next month of features cheaper to build correctly: one handbook instead of five scattered documents, a test suite that fails for real reasons, and two table bugs that would otherwise have kept confusing anyone whose answer from Chalie happened to include a table.

• 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) that all defer to the same manifesto instead of each keeping its own rules

• Audited the test suite against the handbook and removed 5 files and 21 tests that were checking implementation details or duplicating 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 the file-attach flow so a picked file is sendable immediately and the send button shows real send-in-progress state