Docs-drift catalog (standing): known stale documentation and comments #22

New Issue

2026-09-07T05:36:26Z

claude commented

2026-09-07 05:36:26 +00:00

The standing catalog of known stale documentation and comments in this
repository. One comment per finding, appended as reviewers and sweeps turn
them up; cleared by a dedicated docs sweep, then resolved and re-filed empty.

Each entry names the surface as file:line, what the claim says versus what
is actually true, and the PR or sweep that surfaced it.

This issue is deliberately long-lived. It is not worked as a track and it
carries no closing directive, so that it outlives every PR that appends to it.

Per the docs-ship-with-code rule: documentation and comment drift is a
non-blocking nit. A reviewer records it here rather than bouncing the PR that
surfaced it.

The standing catalog of known stale documentation and comments in this repository. One comment per finding, appended as reviewers and sweeps turn them up; cleared by a dedicated docs sweep, then resolved and re-filed empty. Each entry names the surface as `file:line`, what the claim says versus what is actually true, and the PR or sweep that surfaced it. This issue is deliberately long-lived. It is not worked as a track and it carries no closing directive, so that it outlives every PR that appends to it. Per the `docs-ship-with-code` rule: documentation and comment drift is a non-blocking nit. A reviewer records it here rather than bouncing the PR that surfaced it.

claude added the enhancement docs-drift-catalog labels 2026-09-07 05:36:26 +00:00

claude commented

2026-09-07 05:36:52 +00:00

scripts/cache-lib.sh:676-678 — surfaced by the review of PR #21.

The claim, justifying CACHE_CLONE_HEADROOM_FLOOR_KB's 2 GiB default:

cp -al materialises every DIRECTORY for real (only files are linked), and
a Bevy-sized target dir has hundreds of thousands of them.

Measured on a real 46.7 GB zemyna Cargo target dir
(~/.cache/cargo-target/zemyna/zemyna):

find <target-dir> -type d -printf '1\n' | wc -l
3252

3,252 directories, about 13 MB of directory entries at 4 K each — two orders
of magnitude below "hundreds of thousands", and three below the 2 GiB floor it
is offered as the justification for.

The constant itself is fine and errs in the safe direction: the floor usefully
covers the largest single file _unshare_files holds twice mid-copy, which in
a Bevy debug build is a multi-GB linked output. It is only the stated reason
that is wrong.

Per comments-are-not-exposition, the fix is to delete the figure rather than
correct it — a replacement count is a second source that nothing compares
against the tree, and it hands the identical finding to the next reviewer.

**`scripts/cache-lib.sh:676-678`** — surfaced by the review of PR #21. The claim, justifying `CACHE_CLONE_HEADROOM_FLOOR_KB`'s 2 GiB default: > `cp -al` materialises every DIRECTORY for real (only files are linked), and > a Bevy-sized target dir has hundreds of thousands of them. Measured on a real 46.7 GB zemyna Cargo target dir (`~/.cache/cargo-target/zemyna/zemyna`): ``` find <target-dir> -type d -printf '1\n' | wc -l 3252 ``` 3,252 directories, about 13 MB of directory entries at 4 K each — two orders of magnitude below "hundreds of thousands", and three below the 2 GiB floor it is offered as the justification for. The constant itself is fine and errs in the safe direction: the floor usefully covers the largest single file `_unshare_files` holds twice mid-copy, which in a Bevy debug build is a multi-GB linked output. It is only the stated reason that is wrong. Per `comments-are-not-exposition`, the fix is to delete the figure rather than correct it — a replacement count is a second source that nothing compares against the tree, and it hands the identical finding to the next reviewer.

claude commented

2026-09-07 05:42:10 +00:00

README.md:293-294 — surfaced by the spot check of PR 21 (merged as
0184df2).

Every branch merged before the setting was turned on. They stay on
origin forever; nothing retroactively deletes them. zemyna carried 48 of
them at the time the setting was enabled […]

The figure 48 is unsourced and a reader cannot reproduce it. The nearest
derivation available — branches on origin whose tip is already an ancestor of
dev, which is precisely the test this PR added — gives a different number:

git ls-remote --heads origin        # in daniel/zemyna, 2026-09-07
# 61 branches, of which 39 are ancestors of origin/dev

This is not a claim that 48 was wrong. My count is taken after the setting was
enabled rather than at the moment it flipped, and it misses any branch merged
only into main or merged by squash or rebase, so the two are not measuring
the same population. That is the finding: the number names no method and no
moment, so nothing can check it, and the obvious check disagrees.

The argument does not need the value. "They stay on origin forever; nothing
retroactively deletes them" carries the entire point, and the count decays as
those branches are cleaned up with nothing watching it. Per
comments-are-not-exposition's derivable case, delete the figure rather than
correct it — a replacement hands the identical finding to the next reader.

The same figure appears in PR 21's body, which is immutable history and needs
no edit.

**`README.md:293-294`** — surfaced by the spot check of PR 21 (merged as `0184df2`). > **Every branch merged before the setting was turned on.** They stay on > origin forever; nothing retroactively deletes them. zemyna carried 48 of > them at the time the setting was enabled […] The figure `48` is unsourced and a reader cannot reproduce it. The nearest derivation available — branches on origin whose tip is already an ancestor of `dev`, which is precisely the test this PR added — gives a different number: ``` git ls-remote --heads origin # in daniel/zemyna, 2026-09-07 # 61 branches, of which 39 are ancestors of origin/dev ``` This is not a claim that 48 was wrong. My count is taken after the setting was enabled rather than at the moment it flipped, and it misses any branch merged only into `main` or merged by squash or rebase, so the two are not measuring the same population. That is the finding: the number names no method and no moment, so nothing can check it, and the obvious check disagrees. The argument does not need the value. "They stay on origin forever; nothing retroactively deletes them" carries the entire point, and the count decays as those branches are cleaned up with nothing watching it. Per `comments-are-not-exposition`'s derivable case, delete the figure rather than correct it — a replacement hands the identical finding to the next reader. The same figure appears in PR 21's body, which is immutable history and needs no edit.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: daniel/gitdan-actions#22