check-doc-checkpoint treats every root CMakeLists.txt edit as a usage change, so adding a source file demands a docs/USAGE.md edit that has nothing true to say

[localai-bot]

The defect

scripts/check-doc-checkpoint.py lists CMakeLists.txt in USER_USAGE_FILES
(and LANDING_SOURCE_FILES), so any edit to the root CMakeLists.txt
classifies the change as user_usage and demands a docs/USAGE.md edit.

Adding a source file to the library is not a change to how the project is used.
A new src/vt/cpu/*.cpp exposes no command, no config key, no install step, no
C-ABI entry point — there is nothing true to write in docs/USAGE.md for it.
The gate leaves three options, and all three are bad:

1. write something false or vacuous in docs/USAGE.md;
2. weaken the checker (forbidden — and correctly so);
3. don't add the file.

How it surfaced

W1 of KERNEL-SSM-MAMBA (#496, row/KERNEL-SSM-MAMBA-SSD-W1) took option 3.
The spec's port map named a new TU src/vt/cpu/cpu_mamba2_ssd.cpp; the
implementer wrote it, hit this gate, and folded ~430 lines of Mamba2 kernels
into src/vt/cpu/cpu_ops.cpp instead. That is a defensible landing spot — the
GDN and KDA host references are already there — but the file placement was
decided by a doc checker rather than by what belongs together, and the next
kernel author will hit the same wall and make the same call in the dark.

Why this is the checker's defect, not the author's

AGENTS.md, "Records":

A gate is what usually creates the lock: if a checker requires every change
to touch a shared file, that is the defect, not the discipline of the people
touching it. Relocate the obligation to a per-row surface rather than deleting
it.

The same file already carries the argument in its own rewrite note: the previous
version classified by which directory a change touched, produced 16 of the last
20 red CI runs, and accreted six escape hatches. The trigger was fixed for
src/, include/ and tests/ but CMakeLists.txt kept the old shape — it is
still classified by path, not by whether the project's user-facing claims moved.

Suggested direction (not a decision)

Distinguish "a source file was added to the build" from "how the project is
built, installed or invoked changed". Candidates: classify on the content of
the CMakeLists.txt diff (an added source file in an existing target is not a
usage change, while a new option, target, install rule or find_package is);
or narrow the trigger to the install/option surface the way cmake/install.cmake
is already handled separately.

Constraints on the fix

Per AGENTS.md, changing a checker's semantics needs its own spec, a red-before
test or mutation, and green-after evidence, and may not turn a red gate green
by deleting an assertion or widening a scope. This is deliberately filed rather
than fixed in flow.

Found while landing #496. Not blocking it.

[localai-bot]

Second independent instance, same defect class, different prefix.

A separate implementer landing the ModelOpt MIXED_PRECISION resolver (#517 W1) hit it on include/vllm/: check-doc-checkpoint classifies that whole prefix as user-facing and demanded a docs/USAGE.md edit for a header-only file that nothing consumes yet and that is not on the include/vllm.h C ABI. There is nothing true to write in docs/USAGE.md for it.

They took the same escape the first implementer did, in the other direction: the header went under src/vllm/model_executor/layers/quantization/ instead of include/. Recorded in the header, the spec and the commit, with a note that W3 must promote it to include/ once it becomes consumed surface.

So the gate has now moved a file out of include/ and kept another out of its own TU in src/vt/cpu/. Two changes, two different distortions of where code lives, neither decided on structural grounds. That is the shape of the problem: the classifier is asking "which path did you touch" where the rule it enforces is "did the project's user-facing claims change".

Worth folding into the same fix: the trigger should distinguish adding or moving an internal declaration from changing the installed ABI, the build interface, or an invocation surface.