docs: prune TODO.md, and correct four claims that were no longer true

TODO.md becomes a TODO again: only work that is actually queued. Five of
its seven sections were finished work, and their reasoning has permanent
homes — the rules moved to AGENTS.md (the baked rates seed a new dataset
only, never a fallback), the rest is in the commit messages and the
specs. 215 lines to 131.

The four corrections, all of them things a reader would have believed:

- README said the install prompt could not work because the manifest
  "only ships an SVG icon". It has shipped 192x192 and 512x512 PNGs since
  f50c65b. Now stated as unverified rather than incomplete, which is what
  it actually is.
- TODO said no browser had seen the two rule-editing surfaces, while its
  own section 5 listed both as seen and confirmed.
- TODO said "merged to main" when the last three commits were on a
  branch.
- scripts/screenshot.ts explained its own existence by saying
  ARCHITECTURE.md and TODO.md claim no browser can run here. Both now say
  the opposite — partly because of that script.

ARCHITECTURE.md's gotchas section now says AGENTS.md holds the
enforceable form of those rules and this holds the mechanism, so a reader
hitting the overlap knows which is canonical.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Lucas WintherandClaude Opus 5 committed 2026-09-02 21:57:58 +02:00
1 parent 824c2f5f59
commit a039176aa3
4 files changed
+117 -180

No files matched your search

+10 -2
View File
@@ -126,6 +126,10 @@ Adding a "missing" guard here is a regression, not a fix:
## Gotchas paid for with real bugs
`AGENTS.md` §2 carries the enforceable one-line form of these, with the test
that fails when each reappears. What follows is the *mechanism* behind them,
which is the part worth reading once.
- **Never read `event.target.value` inside a `mutate()` callback.** `mutate`
defers behind the queue and a write; React resets a controlled input's DOM
value long before the callback runs, so you read the *old* value and commit
@@ -175,7 +179,11 @@ timing that happy-dom does not reproduce.
## Where the reasoning lives
- `AGENTS.md` — the rules, in enforceable one-line form, and which test fails
when one is broken. This file holds the reasoning; that one holds the rule.
- `docs/PRODUCT.md` — durable product truth: who it is for, what must never break.
- `docs/TODO.md` — queued work, with the reasoning behind each decision already made.
- `docs/specs/` — design decisions and the alternatives rejected.
- `docs/TODO.md` — what is *still* queued, each item carrying the reasoning already
settled. Finished work is not kept there; it is in the commit messages.
- `docs/specs/` — design decisions and the alternatives rejected, one document
per piece of work.
- `docs/plans/` — task-by-task implementation plans.