Twenty-five file headers cite TODO.md section numbers that no longer exist #27

New Issue

tachikoma · 2026-08-02T18:55:21-04:00

tachikoma commented

2026-08-02 18:55:21 -04:00

Source: found while moving TODO.md's open items into this tracker (at 669b2b3)

Roughly 25 file-header comments in tests/ and src/ cite TODO.md by a section
number that no longer exists, and had already stopped existing before the move to
the tracker. They use the old numbering -- §1.1 through §1.9, §2.2.x, §3.1,
§3.6 -- which the pre-move TODO.md itself had renumbered, saying "§3.1 and §3.6
of the old numbering are done".

Examples:

tests/test_memory.c:2      Memory wrappers -- TODO.md section 1.1, now complete
tests/test_linkedlist.c:2  Linked list -- TODO.md section 1.7, complete
tests/test_pool.c:2        Cross-cutting properties -- TODO.md section 1.9
tests/test_version.c:2     Version reporting -- TODO.md section 2.2.16
src/collections.c:2        Data structures -- TODO.md section 3.6
src/string.c:2             string.h wrappers -- TODO.md section 3.1

Every one of them labels completed work, so nothing is misleading about the
code -- what is misleading is the pointer. A reader who follows it finds either a
different subject or nothing at all.

Two ways to close it, and the choice matters more than the edit:

Drop the citation and keep the description (Memory wrappers -- src/stdlib.c).
The provenance is in git history, which is where provenance belongs.
Repoint each at whatever now records that work -- UPGRADING.md for the
defects, this tracker for anything still open.

Option 1 is the recommendation: these comments are labels, not references, and a
label that carries a version-dependent pointer will go stale again the next time
the record is reorganised. This is the second time.

Not done as part of the move because it touches 25 files that had nothing else
wrong with them, and unrelated churn in a documentation commit is how a diff stops
being reviewable.

Filed by Tachikoma (Claude Code, Opus 5, 1M context)

**Source:** found while moving TODO.md's open items into this tracker (at 669b2b3) Roughly 25 file-header comments in `tests/` and `src/` cite `TODO.md` by a section number that **no longer exists, and had already stopped existing before the move to the tracker.** They use the *old* numbering -- §1.1 through §1.9, §2.2.x, §3.1, §3.6 -- which the pre-move `TODO.md` itself had renumbered, saying "§3.1 and §3.6 of the old numbering are done". Examples: ``` tests/test_memory.c:2 Memory wrappers -- TODO.md section 1.1, now complete tests/test_linkedlist.c:2 Linked list -- TODO.md section 1.7, complete tests/test_pool.c:2 Cross-cutting properties -- TODO.md section 1.9 tests/test_version.c:2 Version reporting -- TODO.md section 2.2.16 src/collections.c:2 Data structures -- TODO.md section 3.6 src/string.c:2 string.h wrappers -- TODO.md section 3.1 ``` Every one of them labels **completed** work, so nothing is misleading about the code -- what is misleading is the pointer. A reader who follows it finds either a different subject or nothing at all. **Two ways to close it, and the choice matters more than the edit:** 1. Drop the citation and keep the description (`Memory wrappers -- src/stdlib.c`). The provenance is in git history, which is where provenance belongs. 2. Repoint each at whatever now records that work -- `UPGRADING.md` for the defects, this tracker for anything still open. Option 1 is the recommendation: these comments are labels, not references, and a label that carries a version-dependent pointer will go stale again the next time the record is reorganised. This is the second time. **Not done as part of the move** because it touches 25 files that had nothing else wrong with them, and unrelated churn in a documentation commit is how a diff stops being reviewable. --- Filed by Tachikoma (Claude Code, Opus 5, 1M context)

tachikoma added this to the 0.2.x milestone 2026-08-02 18:55:21 -04:00

tachikoma added the docs hygiene blast-radius:low status::grooming labels 2026-08-02 18:55:21 -04:00

tachikoma referenced this issue

2026-08-02 18:55:57 -04:00

Move outstanding work from TODO.md into the issue tracker #28

tachikoma referenced this issue from a commit

2026-08-02 22:02:22 -04:00

Drop the TODO.md section numbers from 26 files

Sign in to join this conversation.