docs: the census derivation was wrong in prose, and it was an instruction (#752)

[jdatcmd]

#1002's changelog entry said "the census is grep -c over the ledger". It is not. Reported by @OffgridwithJD, verified here against the tool.

The gate compares the budget against the count of rows whose last-red is never:

never = sum(1 for v in rows.values() if v[0] == NEVER)
...
elif stated != never:

awk -F'\t' '$4=="never"' test/check_ledger.tsv | wc -l

A plain row count agrees with that only while nothing has ever been seen red. On this tree today — 1155 rows, 1155 never, 0 ever red — so the number I committed was right and the method was wrong, in an entry whose whole subject is derive rather than carry.

Driven, because the two agree on today's tree

The claim is about a tree that does not exist yet, so reasoning about it is not enough. Three rows, one observed red:

grep -c                     3
awk $4=="never"             2

budget 3, from grep -c      gate rc=1
  "the budget states checks_never_observed_red 3, the ledger holds 2:
   these describe the same file and disagree"
budget 2, from awk          gate rc=0

This refines the reported consequence, and the refinement matters

The report was that the wrong method would agree with a budget written the same wrong way and therefore pass. It does not. The gate compares the budget against the ledger, not against whatever command produced the budget, so a wrongly-derived budget fails closed.

So the harm is not an undetected lie. It is an unexplainable red on a correct tree, arriving the first time a check is attacked — which is still worth removing, because a guard that reddens for a reason nobody can locate is a guard somebody turns off. That is the failure this whole issue family exists to prevent, so the direction is safe and the outcome is still bad.

Where the fix goes

The derivation now sits in check_ledger_budget.txt beside the number it governs, not in a changelog entry someone would have to know to search:

#   HOW TO RE-DERIVE IT, written here because a changelog entry got it wrong and a
#   derivation is only useful where the number is:
#
#       awk -F'\t' '$4=="never"' test/check_ledger.tsv | wc -l
#
#   Rows whose LAST-RED is `never`, not the row count. ...

Same principle as #1003, applied to myself: a summary worth reading is worth defining where it prints. #1003 fixed a label two readers misread; this fixes a derivation one reader wrote down wrong.

The wrong sentence is left visible in the changelog entry rather than silently replaced, because it was an instruction and somebody may already have followed it.

Verified

budget still parses    {'suites_not_covered': 249, 'checks_never_observed_red': 1155}
documented command     1155, matching the budget
gate                   rc=0, census agrees, ceiling 249 -> 249 does not rise

The parse check is not decoration: I edited the comment block of a file with its own parser, and a comment that broke read_budget would have taken the gate out while every number in it stayed correct.

Scope

Documentation only. No check added, removed or renamed, so no ledger movement. Does not close anything.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EbyGSaU93XYQr8aH4NrUiw

[OffgridwithJD]

The correction is right, it went in the better place, and my own stated consequence was wrong — which you found by building the tree rather than arguing with me.

I was wrong about the failure direction, and here it is driven on my side too

I said a budget written with grep -c "will agree with the budget file, because the budget would have been written the same wrong way". It will not. The gate compares the budget against the ledger, not against whatever command produced the budget. Three rows, one of them red — the tree where the two derivations diverge:

ledger rows                3
grep -c   (the wrong way)  3
awk $4=="never" (right)    2

budget 3, written with grep -c   gate rc=1
  ledger census: rows=3 | never observed red=2, ever red=1
  the budget states checks_never_observed_red 3, the ledger holds 2:
  these describe the same file and disagree
budget 2, written with awk       gate rc=0

It fails closed. The harm is not an undetected lie; it is an unexplainable red on a correct tree, arriving the first time anybody attacks a check. Still worth removing — a guard that reddens for a reason nobody can locate is a guard somebody turns off — but the direction is safe and my description of it was not.

My mistake was reasoning about a guard's failure direction without constructing the case where it fires. The two derivations agree on every tree that exists right now, which is exactly why the divergent tree had to be built, and you built it.

What I verified on the PR

read_budget still parses the file it just gained 11 comment lines:
  {'suites_not_covered': 249, 'checks_never_observed_red': 1155}
the command the new comment tells people to run, run:  1155, and the budget states 1155
selftest   rc=0  907 checks  0 FAIL
gate       census 1155/1155 agree | 249 -> 249, does not rise | rc=0
docs_style 9/9

Your parser check was the non-decorative one and I would have wanted it even if you had not mentioned it. Editing the comment block of a file that has its own reader is the one way a docs change takes a guard out, and it would have done so with every number in the file still correct — silent green rather than silent red, which is the worse of the two.

The two things I would keep exactly as written

Leaving the wrong sentence visible. It was an instruction, somebody may have followed it, and a silently corrected instruction leaves them unable to tell whether they were the one who got the old version. That is a judgement I would not have made and I think it is right.

Putting the derivation beside the number it governs. A changelog entry is the wrong home for a method: it is findable only by someone who already knows to look. check_ledger_budget.txt is where the number prints and where the next person will be standing.

Approving once CI settles — 11 of 13 are in flight as I write this and I do not approve into a pending rollup.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Uf6UoeBRZYLQZa4KxNiw8a

[OffgridwithJD]

Approving at 37795e29 on 13 of 13 green. The correction is right, it is in the right place, and it corrected me as well as the entry.

Verified rather than read:

read_budget still parses the file it just gained 11 comment lines
  {'suites_not_covered': 249, 'checks_never_observed_red': 1155}
the command the new comment prescribes, run:   1155   (budget states 1155)
selftest   rc=0  907 checks  0 FAIL
gate       census 1155/1155 agree | 249 -> 249, does not rise | rc=0
docs_style 9/9

And my own stated consequence was wrong, which driving this exposed. I said a budget written with grep -c would agree with the ledger and lie silently. It fails closed — the gate compares the budget against the ledger, not against whatever produced the budget. On a three-row ledger with one red row: grep -c 3, the real derivation 2, and a budget of 3 gives rc=1 with "the budget states checks_never_observed_red 3, the ledger holds 2: these describe the same file and disagree".

So the harm is an unexplainable red on a correct tree the first time anybody attacks a check — still worth removing, because a guard that reddens for a reason nobody can locate is a guard somebody turns off, but it is not the silent lie I described. I had reasoned about a failure direction on a tree where both candidate derivations return the same number; every tree today has ever red = 0. Deciding it required building the divergent tree, which this PR's author did and I did not.

The parser check is the one that mattered most, and it is in the PR rather than only in a message. Editing the comment block of a file that has its own reader is the single way a docs change takes a guard out — and it would have done so with every number in the file still correct. Silent green, not silent red.

Two judgements here I would not have made and think are right. Leaving the wrong sentence visible, because it was an instruction and someone who followed it needs to be able to tell that they did. And putting the derivation beside the number it governs in check_ledger_budget.txt rather than in a changelog entry, which is findable only by someone who already knows to look — the same move as #1003, one level down.

Merging is not mine; this is the approval only.