d7bafa93

docs: use it like an end user would

a73x 2026-08-26 12:20

Commit message

docs: use it like an end user would

Three escapes in one week all had one shape: the fixture could not express
the failing case. Every test held one session, so aliased session names
survived 80 green e2e scenarios; `col_off` was 0 in every test body, so a
tile painting over its neighbour survived; nothing executed the page, so
the page's rules went unpinned. None of that is diligence — it is fixtures
pinned to their degenerate value.

The third rule is the one the upgrade work earned: the daemon's own report
cannot catch the daemon being wrong, so the witness is /proc.

CLAUDE.md

Old		New
@@ -118,7 +118,21 @@ real pty), `wsclient` (browser stand-in), `rawmode`, `delaypipe`, `render`.
118		118
119	## Working rules	119	## Working rules
120		120
121	- Assert behavior, don't assume it. Mocks are assumptions.	121	- Assert behavior, don't assume it. Mocks are assumptions. Use the thing
		122	the way an end user does — real binaries, a real pty, a real shell. A
		123	fixture that stands in for the product tests the fixture.
		124	- A fixture that holds a dimension constant is blind to that dimension.
		125	Where a thing can be plural — sessions, tiles, dials, panes — the DEFAULT
		126	fixture is plural; where a thing has an origin, the default is off-origin.
		127	N=1 and offset=0 are extra cases, never the baseline. Three escapes in one
		128	week were each exactly this, and all three passed a green gate: session
		129	names aliased their neighbour's because every test held ONE session; a tile
		130	painted over the rail because `col_off` was 0 in every test body; the
		131	page's own rules went unpinned because no check executed the page.
		132	- Ask the OS about the OS, not the daemon. A claim about a pid, an fd, a
		133	socket or a process tree is asserted against `/proc`, `ps`, or the shell's
		134	own `$$`. A daemon reporting on itself cannot catch itself being wrong —
		135	which is why `muxd upgrade`'s gate is a shell pid read off the grid.
122	- Comments say why, not how. Existing ones are load-bearing — trim noise,	136	- Comments say why, not how. Existing ones are load-bearing — trim noise,
123	keep rationale. `zig build check` gates the claims (symbol refs must	137	keep rationale. `zig build check` gates the claims (symbol refs must
124	resolve, no history codenames in src comments, and every file's flagged	138	resolve, no history codenames in src comments, and every file's flagged