docs: traps.md — the bugs that passed a green suite

Six bugs this project shipped into a branch, what let each through, and the
guard that now catches it. They share a shape: the test passed, and the test
was wrong.

- a regression test that constructed its own correct object, so reverting the
  bug left the suite green
- GDScript default params turning an arity change into a silent miscompile,
  invisible to a grep for the renamed field (grep cannot see positional args)
- a determinism test comparing two runs that would change together
- a closed move vocabulary that was not bounded, because the model could repeat
  a tag and choose an amount in unary
- a roster written down in four places with only one pair guarded — including a
  shipped authoring skill that would have emitted origins allowing zero callings
- generated content that has a client consumer

Linked from CLAUDE.md §18 and docs/README.md. Also records M4-a on the roadmap
with its live end-to-end proof.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QYa9u7Kdxv5gX4AnwWexy8
This commit is contained in:
2026-07-12 21:07:39 -05:00
parent b663703da7
commit b4b72e472e
4 changed files with 138 additions and 0 deletions

View File

@@ -559,6 +559,12 @@ contracts (§12), and Failure UX (§13).
- **When a request conflicts with this document, say so.** Do not silently comply. This file is the argument; if it is wrong, change the file first.
- **When adding a system, state which side of §2 it falls on.** State or text. If it is both, it is two systems.
- **Prefer deleting scope.** The POC's value is answering one question fast.
- **A green suite is evidence only if the test can fail.** Before accepting a fix that
claims to guard a regression, re-break the code and *watch the new test fail*. This
project has shipped a regression test that passed against its own bug, a determinism
test that compared two runs that changed together, and an arity change that
miscompiled silently past a clean grep. Read **[docs/traps.md](docs/traps.md)** before
writing tests — it is six ways this codebase has already fooled a green suite.
### Git workflow