[piyushmakhija28]

Closes item 1 of #296.

Seven of the nine file counts CLAUDE.md and README.md advertise were wrong, two by more than a factor of two:

Claim	Said	Actual
langgraph_engine/*.py	244	253
repo-wide *.py	395	493
test_*.py	45	100
unit tests	36	91
integration tests	4	5
docs/ files	156	255
e2e / load	3 / 1	3 / 1

README.md separately claimed 44 for the same figure CLAUDE.md put at 45, in two different places. Two documents drifting to different wrong values for one number is only possible when neither is checked against anything, and that — not the arithmetic — is what this PR is about.

The approach is borrowed, not invented

docs/README.md carries the same kind of counts and they are correct, because tests/test_docs_index_matches_the_tree.py compares them against a live enumeration of the tree. This applies that technique to the remaining two files so the drift cannot recur, rather than fixing it once and waiting for it to happen again.

Counts come from git ls-files, not the filesystem, for the reason that test records in its own docstring: the documentation describes the repository, not whoever's working tree is on disk. Its first version counted os.listdir and passed locally while failing in CI, because a gitignored analysis dump existed on one machine and in no clone.

What is deliberately not checked

CLAUDE.md's 578 classes, 3,985 methods call-graph figures would need a full AST build per test run and would churn on any code change. Its 13 servers MCP count describes repositories that cannot be enumerated from here. A check that is expensive, or that cannot see its subject, teaches people to ignore it — so neither is asserted.

Verified rather than assumed

The test was written first and watched fail on all fourteen claims before a single number was corrected, so it is known to read the real files rather than pass vacuously. test_every_claim_pattern_matches_its_file guards that property permanently — a regex that stops matching its file is otherwise a silent pass, which is exactly the failure mode being fixed.

Its own guard caught a bug in its own counters. _test_modules_in added one to the prefix depth, so "unit tests" reported the nine files one level deeper (tests/*/test_*.py) and the three per-directory counters reported zero. test_no_counter_returns_zero failed and named them. The arithmetic guard alone would not have caught it — 9 + 0 + 0 + 0 still equals 9 — which is why both guards exist.

Adding this file changes the numbers it checks. It is a tracked test_*.py, so the totals it must assert are the post-commit ones (100 / 91 / 121 / 493), not the ones measured before staging it. Confirmed by staging the file and recomputing from the index rather than by predicting the increment — a test that went red on its own merge commit would have been a poor advertisement for the idea.

Local: the new file and test_docs_index_matches_the_tree.py pass together (13 tests), every test that reads CLAUDE.md or README.md passes, verify_open_encoding and verify_home_paths pass, collection is clean, and git diff --numstat shows 2/2 and 8/8 rather than whole-file line-ending flips.

CI is the authority on Linux and on py3.10/3.11 — the last PR proved that distinction the hard way.

🤖 Generated with Claude Code