Eleven minor findings from the review council, all of the same family: a
statement that was true when written and was not updated when the thing it
counted grew. Fixing the ones that are wrong TODAY; the coverage gaps the same
lenses found are filed rather than fixed here.
THE ONE THIS SERIES CAUSED. The ghost-cleanup commit (8baf16989) collapsed a
"drives all six" / "drives all five" ghost pair in roles_test.go into "drives
every database-touching operation" — reaching for a sentence the next role
would not invalidate, and landing on one that was false immediately. The test
drives ten of the sixteen capability-bearing operations in routes.go; the other
six are covered in their own files. The doc now says which ten, where the rest
live, and why the sentence must not be generalized a third time. That is the
better lesson than the fix: a future-proof phrasing bought at the cost of a
present-tense falsehood is a worse trade than the stale count it replaced.
THE PUBLISHED DOCUMENT CONTRADICTED ITSELF. openapi.v0.yaml called sweep "the
only DESTRUCTIVE operation on this surface" eighty-five lines above calling
delete "the second DESTRUCTIVE operation". Both now name the pair. The pinned-
schemas header carried a merge ghost — "Each of the eight below" immediately
followed by "Each of the ten below" — where the real count is twelve, as the
paragraph nine lines further down already said. Same claim in problem.go and
sweep.go.
sweep.go also said ErrValidation is a 400 "HERE and nowhere else yet". Five
more handlers draw that line now (delete, tree, edges, blocking, batch-create),
each deliberately in the same shape. The comment says so, and keeps the reason
ClassifyError is still not the place for it.
claim.go said IssueReader and IssueClaimer "are the two places where a
constructor is the right call". timedProvider now has thirteen, every one of
them correct — this is the single type in the codebase where a constructor
beats an accessor, because the whole point is to bind the role to the TIMING
wrapper rather than to the provider inside it. A reader who took the sentence
literally would conclude the other eleven are violations and "fix" them into
uow_ms=0.000 for every write route. StatsReporter also introduced itself as
"the third time" while being the fourth.
execution.go justified CreateRequest having no Provenance field with "no
surface has ever named the created issue in its commit message". That is false
— internal/storage/dolt/issues.go writes "bd: create <id>" and is reached from
cmd/bd/create_atomic.go — and it is the premise wave 1 reasoned from when it
let the proxied route's message change to "create issue". The comment now says
what is actually true: the field does not exist, so there is no label to
prefer, and that is a gap with two possible closures rather than a principle.
CHANGELOG: the programme-close entry said "sixteen operations, ten of them
added by the programme" — main carries four, so it added twelve. The wave-2
entry said "adds five" above a list of six, which its own arithmetic (6 + 6 =
twelve) already contradicted. And the sweep endpoint's entry documented two of
its three safety properties, omitting protect_referenced — the one that needed
owner adjudication, and the only place the HTTP default deliberately disagrees
with the CLI flag it mirrors. It says so now, including how to opt out.