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.

claude commented

2026-09-22 16:08:53 +00:00

One entry from PR #25's final review (unprotect publisher target dirs, closes #24).

scripts/prune-cache.sh:253-254 — is_locked's rationale says "Today no reachable configuration prunes a snapshot (only protected refs publish them, and protected refs are excluded from every pass)". The parenthetical is now false: after PR #25 only a protected ref's snapshot is excluded from every pass (protected_ns, :204); its target dir is an ordinary pressure-pass candidate (protected_target_ns, :205, consulted by is_protected_from_liveness in pass 1 alone). The conclusion the parenthetical supports — that no snapshot is prunable — remains true via the snapshot half alone, so nothing downstream is wrong; only the reason given for it is.

Drift rather than authored-false: the sentence was true when written, the diff made it untrue, and protected_reason:218-225 sits beside it carrying the correct fact. The parallel sentence at README.md:250 was corrected in the same diff; this one was missed.

Recommended when someone is next in the file: narrow the clause to "and a protected ref's snapshot is never an eviction candidate", matching the README's corrected phrasing — or delete the parenthetical and let protected_reason speak for itself. Per comments-are-not-exposition, deleting beats correcting where the code beside it already carries the fact. Surfaced by PR #25.

One entry from PR #25's final review (unprotect publisher target dirs, closes #24). **`scripts/prune-cache.sh:253-254`** — `is_locked`'s rationale says "Today no reachable configuration prunes a snapshot (only protected refs publish them, and protected refs are excluded from every pass)". The parenthetical is now false: after PR #25 only a protected ref's **snapshot** is excluded from every pass (`protected_ns`, `:204`); its **target** dir is an ordinary pressure-pass candidate (`protected_target_ns`, `:205`, consulted by `is_protected_from_liveness` in pass 1 alone). The conclusion the parenthetical supports — that no snapshot is prunable — remains true via the snapshot half alone, so nothing downstream is wrong; only the reason given for it is. Drift rather than authored-false: the sentence was true when written, the diff made it untrue, and `protected_reason:218-225` sits beside it carrying the correct fact. The parallel sentence at `README.md:250` was corrected in the same diff; this one was missed. Recommended when someone is next in the file: narrow the clause to "and a protected ref's snapshot is never an eviction candidate", matching the README's corrected phrasing — or delete the parenthetical and let `protected_reason` speak for itself. Per `comments-are-not-exposition`, deleting beats correcting where the code beside it already carries the fact. Surfaced by PR #25.

claude commented

2026-09-22 21:11:34 +00:00

.gitea/workflows/release-sweep.yaml (as it lands from PR #28, ca0ee13): the sweep repeats ci.yaml's selftest job steps (toolchain setup, shellcheck, selftest.sh) instead of sharing them, so the two gates can drift apart. If they do, the sweep will release commits under a different gate than the merge path. The fix is to factor the gate into one script, or into a reusable workflow both call.

Surfaced by PR #28's final review.

**`.gitea/workflows/release-sweep.yaml`** (as it lands from PR #28, `ca0ee13`): the sweep repeats `ci.yaml`'s selftest job steps (toolchain setup, `shellcheck`, `selftest.sh`) instead of sharing them, so the two gates can drift apart. If they do, the sweep will release commits under a different gate than the merge path. The fix is to factor the gate into one script, or into a reusable workflow both call. Surfaced by PR #28's final review.

claude commented

2026-09-22 23:13:24 +00:00

scripts/release-v1-selftest.sh, scenario 9's comment ("C2's job was cancelled in the concurrency group"), and PR #28's body ("Gitea's concurrency cancellation can strand…"): both describe a stranding that ci.yaml now rules out by design, since release-tag no longer carries a job-level concurrency group. It stays possible only under the older, unverified Gitea behaviour. Hedged, so drift rather than authored-false. Fix: reword the scenario's framing to "a run that deferred and left no newer run behind it".

Surfaced by PR #28's final review.

**`scripts/release-v1-selftest.sh`, scenario 9's comment** ("C2's job was cancelled in the concurrency group"), and PR #28's body ("Gitea's concurrency cancellation can strand…"): both describe a stranding that `ci.yaml` now rules out by design, since `release-tag` no longer carries a job-level concurrency group. It stays possible only under the older, unverified Gitea behaviour. Hedged, so drift rather than authored-false. Fix: reword the scenario's framing to "a run that deferred and left no newer run behind it". Surfaced by PR #28's final review.

claude commented

2026-09-22 23:15:15 +00:00

README.md:651-652 (Versioning section): says the release token's contents: write grant is "unobserved until the first merge". It has now been observed. PR #28's merge ran release-tag successfully and moved v1 to 0284fcd (recorded on #27). Fix: say it is verified, and keep the note that it is capped by the repository and owner token-permission maxima.

Surfaced by the post-merge AC3 check for PR #28.

**`README.md:651-652`** (Versioning section): says the release token's `contents: write` grant is "unobserved until the first merge". It has now been observed. PR #28's merge ran `release-tag` successfully and moved `v1` to `0284fcd` (recorded on #27). Fix: say it is verified, and keep the note that it is capped by the repository and owner token-permission maxima. Surfaced by the post-merge AC3 check for PR #28.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: daniel/gitdan-actions#22