check-doc-count.py prints a clean verdict over a scan that read nothing, and its OK line names no coverage #2053

Measured 2026-10-10 (cyc20261010-194528) on master 7af944f4.

scripts/check-doc-count.py answers 0 for a scope it read no file from, and its
clean verdict names no coverage. Both halves are the family's rule; this guard is the
member that does not carry it.

The two readings

$ uv run --no-sync python3 scripts/check-doc-count.py
tree: /Users/argszero/.emrg/evolution/emrg
OK: no tracked file states the Python test count (it is measured, not stored)

How many files that sentence covers is nowhere in the output. The module's own Scope
paragraph says the opposite: "'which files did you scan' is the one thing this rule
must not answer vaguely."

$ cd <a tree whose every file is under tests/ or scripts/>    # the export path, no .git
$ uv run --no-sync python3 scripts/check-doc-count.py
tree: <that tree>
OK: no tracked file states the Python test count (it is measured, not stored)    # rc 0

The same sentence and the same code come back from a git tree whose git ls-files
lists only those two directories. 0 is the code that means measured and clean.

The file already states the rule, and enforces it one branch early

tests/test_check_doc_count.py::test_unlistable_files_fail_loud says what the guard
must not allow, in its own words:

"I could not check" reported as healthy is how a broken tree reaches master: an
empty scan and a clean tree are indistinguishable in the output.

Only the listing failure has a branch (DocCountError -> rc 2). An empty listing is
the same defect one step later, and there the guard passes.

The test that pins the defect sits in the same file:

monkeypatch.setattr(mod, "scanned_files", lambda: [])
assert mod.main([]) == 0

test_the_scanned_tree_is_named_in_the_output stubs the scan to nothing and requires
exit 0, so the guard cannot be fixed without rewriting it. Its subject is which tree
gets named and the stub is incidental; the assertion is not.

Why this is not merely theoretical

The scope is declared as "every tracked file except tests/ and scripts/", so the two
directories that hold the rule and its probes are exactly the ones that can empty the
subject - an export carrying only them (this guard already runs on git archive exports,
through check-merge-sequence.py), or a checkout whose index holds only them.
tests/test_doc_counts.py::test_the_scan_scope_covers_every_tracked_doc asserts
scanned is non-empty, so the emptiness is visible from inside the suite and from
nowhere in the tool's own verdict.

Precedent

• Two tree-reading guards answer a clean verdict over a tree they read no file from - and one documents that it refuses #1872 (merged): check-citation-resolves.py and check_unbound_reads.py - the same
  pair of readings, refuse an empty subject (rc 2, naming which of the two it read) and
  name the coverage in the clean verdict.
• check_nonlocal covers nothing when its four inner functions all move, and its OK line names no coverage #2047 -> PR emrg: the nonlocal check refuses an empty subject and names what it read #2048: check_nonlocal.py covers nothing when its four inner functions
  move, and its OK line names no coverage.
• emrg: the GUI-breakdown guard skips a part it cannot read, so a line naming three parts can be certified from two #1924: a guard that skips a part it cannot read certifies a line naming three parts
  from two - this guard skips unreadable files in silence as well.

Acceptance

• a scan that read no file refuses with rc 2 and a could not measure line naming the
  tree and the two excluded directories - never a clean verdict;
• the clean verdict names how many files were read, and how many were skipped as
  unreadable, so no claim in the whole scope and no claim in none stop being the same
  sentence;
• the test that requires the empty scan to pass is rewritten, and both directions are
  pinned (empty refuses, non-empty still passes).