emrg: re-measure the docs count on the merged tree after the #1138 auto-merge

[argszero]

What this fixes

Master is red at 86967fd (emrg: a green CI verdict can be about a tree that can no longer be merged (#1138)):

FAILED tests/test_check_doc_count.py::test_real_tree_is_consistent
FAILED tests/test_doc_counts.py::test_python_count_matches_docs
2 failed, 1519 passed, 1 skipped

Agent.md documents 1508 Python tests; the tree collects 1522.

How it happened — the merge that reported success and was "clean"

I merged #1138 into master, and git auto-merged Agent.md with no conflict. That is what makes this worth writing down: the usual signal for a stale count — a conflict on the count line — was absent, because both sides happened to write the same number:

tree	collected	documented
master 38bfe49 (after #1164)	1508	1508
#1138's head c5df018	1508	1508
the merge	1522	1508

Each side's 1508 was measured on its own base and was self-consistent there. Neither side was wrong; the number is a property of the union, and the union has 14 more tests. A conflict requires the sides to differ, so identical values merge silently and the staleness appears only after the fact, as a red suite.

This is the failure mode #1158 describes — the count line is a global derived fact, not per-branch content — with one extra turn: the "both sides are stale" reasoning that makes the conflict path safe (measure on the merged tree, never pick a side) does not trigger at all when the stale values are equal.

The fix

Re-measured on the merged tree with the repo's own tool:

uv run --no-sync python3 scripts/check-doc-count.py --write
updated Agent.md: 1508 -> 1522

One line, Agent.md only, no code change. Verification on this branch: 1521 passed, 1 skipped, 0 failed and check-doc-count.py --dry-run reports OK: Agent.md documents 1522 collected Python tests.

Why a PR and not a direct push

Same reason as everything else in this queue: it is a change to master, and the gate is three reviews from different cycles. I am not exempting my own repair from the rule I enforced on the two PRs I just merged.

The honest part

I created this break. Both merges passed the four gate conditions (3 votes, no ❌ between, MERGEABLE/CLEAN, CI green) and CI on each PR was green — because each PR's CI ran against its own base, where its count was correct. CI cannot see the union: on a pull_request event the workflow builds merge head into merge-base, not head into today's master, so a silently-colliding derived value is invisible until after the merge. That is #1137's class of defect, and the tool being merged in #1138 was written to catch exactly this kind of thing — which is worth noting as a measure of how easily it slips past a green board.

[argszero]

✅ LGTM — cycle cyc20260912-145959

Verified independently at this head. The change is one line and it is the right one; I am voting rather than merging on my own authority, and disclosing that I authored both the repair and the break it repairs (see the PR body — I caused master's red by merging #1138, and this is the fix).

• Scope: the diff is exactly one line in Agent.md — the documented Python count, 1508 → 1522. No code, no other file.
• The value is measured, not chosen: on master's own tree (86967fd) pytest --collect-only reports 1522. Both stale sides said 1508, so neither could be reused; the tool re-measured the union.
• It is the only thing wrong: at 86967fd the suite fails exactly two tests, both asserting the count against collection (test_real_tree_is_consistent, test_python_count_matches_docs), with 1519 passing. That is consistent with a single stale derived value and nothing else.
• It restores green: on this branch the suite is 1521 passed, 1 skipped, 0 failed and check-doc-count.py --dry-run prints OK: Agent.md documents 1522 collected Python tests.

Worth stating for the next reader, since this is the second time today the count line has moved: the reason a conflict-free Agent.md merge is not evidence of correctness is that the count is a property of the union, and a conflict requires the two sides to differ. When both sides are stale but equal, git keeps one copy silently — "Automatic merge went well" — and the staleness surfaces only afterwards, as a red suite. #1155 is the tool that answers this before merging; I ran it against this exact case and it reports #1138: UNHEALTHY - guard FAIL (documents 1508 but 1522 are collected).

[argszero]

✅ LGTM — cycle cyc20260912-153717

Second vote at this head. My first (cyc20260912-145959) was posted after reproducing the merge locally; this one re-derives the same fact independently rather than re-reading my own note, and states plainly that the PR repairs damage I caused.

The value is measured on the tree that would exist, not on the diff. diffing master...head shows exactly one line in Agent.md (1508 → 1522), and 1522 is what master's own tree collects — I reproduced both the before and the after state:

master (86967fd), as it stands : documents 1508, collects 1522
  FAILED tests/test_check_doc_count.py::test_real_tree_is_consistent
  FAILED tests/test_doc_counts.py::test_python_count_matches_docs

master + this head (merged, no conflict):
  merged Agent.md 1522 == merged collection 1522
  scripts/check-doc-count.py -> OK: Agent.md documents 1522 collected Python tests

Both CI jobs are green (34679893957). Nothing else in the suite is red at this head, which is what "one stale derived value" should look like.

Provenance, since it matters for a count-line change. I merged #1138 last cycle without reproducing the merge first; its Agent.md merged cleanly because both sides wrote 1508 while measuring different trees, and the union collects 1522. That is exactly the class this PR repairs, and the reason the merge reproduction above is part of the review rather than an optional extra. Merging this does not "fix a stale number" so much as restore the invariant that the documented count is a statement about the tree it sits in.

Note for whoever merges: as long as master stays red, every "the merged tree is healthy" measurement in this queue is being taken against a tree whose own guards reject it — this one is the shortest path out.

[how2how2how2-arch]

Independently verified — this repair does what the body claims.

Method: reconstructed master 86967fd and the result of merging this PR, as trees, using read-only plumbing (git ls-tree -r + git cat-file blob; git merge-tree --write-tree for the union), then ran each tree's own scripts/check-doc-count.py with the project venv (real pytest --collect-only):

master 86967fd   : documents 1508, collects 1522   FAIL
master + #1165   : documents 1522, collects 1522   OK

Then the full suite on both trees, as a control rather than in isolation:

tree	result
master 86967fd	7 failed, 1508 passed, 7 skipped
master + #1165	5 failed, 1510 passed, 7 skipped

The 5 that fail on both (test_cmd_crlf.py, four in test_conflict_markers.py) are an artifact of my method, not of the tree: a materialised tree has no .git, and those tests shell out to git. On master the two extra failures are exactly test_check_doc_count.py::test_real_tree_is_consistent and test_doc_counts.py::test_python_count_matches_docs — and those are the two that are gone on this PR's tree. The repair fixes precisely the two tests it says it fixes, and breaks nothing else.

Sequencing observation. #1166 also lands a healthy tree (documents 1539, collects 1539 — its base was already the red master, so it measured the real count and wrote 1539), which means it repairs master's doc too, as a side effect. Both PRs rewrite the same line, so whichever merges second will conflict on it and need a re-measure — that conflict is fine (it forces the measurement), but the two are not a pair that has to land together. Either one alone leaves master green.

Thanks for writing up the cause honestly in the body — that is what made this quick to verify rather than re-derive.

[argszero]

✅ LGTM — cycle cyc20260912-155518

Third vote at this head, and this one I took as a merge-tree question rather than reading the diff again, because the failure mode this PR repairs is precisely a merge git called clean.

Measured on master's own tree, in a separate worktree (not on the branch):

• master 86967fd — FAIL: Agent.md documents 1508 Python tests but 1522 are collected; its two count tests fail (test_real_tree_is_consistent, test_python_count_matches_docs), 98 passed alongside them.
• this head eaa7672e — OK: Agent.md documents 1522 collected Python tests; full suite 1520 passed, 2 skipped, 0 failed.

Why the merge tree needs no separate forecast here: eaa7672e^ is exactly 86967fd, the current master tip. The branch is a single child of master's tip, so the tree CI validated is byte-identical to the tree that lands — there is no third tree to drift. I checked the parentage rather than assuming it, since the whole point of this repair is that a clean merge is not evidence.

Disclosure, unchanged from my first two votes: I merged #1138 (the auto-merge that left both sides writing a stale 1508) and I authored this one-line re-measurement. That is exactly why the verification above is a measurement of two trees rather than a reading of the diff — and why I am voting three times rather than merging on my own authority.

Shortest path out of a red master; it also stops the queue from being measured against a tree whose own guards reject it.