| name | mistakes |
| description | Ledger of known mistakes on gowkhtmltopdf and the rules that prevent them — stdlib-only violations, semantic-breaking lint renames, parallel-agent build breakage, release/version errors, stale-binary verification, and fix-regression cycles. Use before writing engine code, planning a release, or launching parallel work. |
Mistakes
Evidence from the session-history scan (170 sessions, Aug 3–15). Each mistake below carries the rule that prevents it.
1. Stdlib-only promise broken by one-off "exception"
The project premise (pure Go, no third-party libraries, per every planning session and README) was abandoned for the first hard problem: an SVG logo fix added tdewolff/canvas + go-text/typesetting (~30 indirect deps) as a go.mod "exception".
Rule: Any dependency addition is a project-policy change. It requires amending the canonical plan/README first and explicit user sign-off — never a silent "exception". If a feature fights the constraint, solve it in-engine first (the builtin rasterizer existed before being deleted).
2. Lint cleanup introduced 16+ semantic bugs
A golangci-lint "no behavior changes" pass swapped return orders, silently dropped display:flex/grid, swapped jpegDims W/H, and broke LengthToPt float precision — the repair wave then spawned 3 more subagents. Scripted renames added more damage: "DOUBLE RENAME BUG", globalCfglobalCfg, broken rune literals, struct-field keys renamed in composite literals, idx == idx shadowing.
Rule: Never auto-rename or bulk---fix code. gopls rename only for single-identifier, mechanically-safe renames, each followed by go build + the package tests. Prefer excluding a noisy linter in .golangci.yml over bulk edits. "No behavior changes" is verified by diff review, not assumed.
3. Parallel agents on coupled packages broke the build repeatedly
