protocol(doc-gate): preflight checks the committed RANGE — --staged was vacuous

[localai-bot]

Self-reported protocol violation from PR #80, and the gate change that prevents it recurring.

What went wrong

PR #80 (Vulkan) landed eight commits that touched src/ and tests/ without updating docs/STATUS.md and docs/BENCHMARKS.md in the same commit, so documentation-checkpoint failed for that push range on main:

9579f94e, ba5ea0cf, 196ea46f, e32c5ed3, 3bfa1f12, 34a3efe6, 2c86f79e, f4738bb8

Each deferred its doc update into a following record(...) commit.

Why it passed locally — the part actually worth fixing

check-doc-checkpoint.py --staged inspects the staged paths. It is therefore vacuous when nothing is staged — which is the normal state after git commit, and exactly when agent-preflight.sh runs it. The gate reported OK on every one of those commits while checking literally nothing.

CI is diff-scoped over the pushed range and checks each commit independently, so the failure only appeared on main — where, by that job's own design, a diff-scoped range is never re-covered by a later run.

The fix

agent-preflight.sh now runs --base origin/main --head HEAD whenever the branch is ahead of main, reproducing CI's verdict locally in seconds.

That check sits outside the --staged block, deliberately. My first attempt nested it inside, which reproduces the identical hole one level up: --staged is precisely the flag you are not passing when the range goes unchecked. Caught by the gate catching my own commit, which is the best evidence it works.

Verified two ways:

• prints ok doc-checkpoint range on this branch;
• pointed at the Vulkan: a model runs end to end, token-exact — 16 native kernels, variant pipeline, two CI gates #80 range (075b9f21..0be5d457) it raises 20 errors naming every offending commit.

workflow.md carries the same instruction with the reason, so the next series doesn't rediscover it.

What is not being done

History is not being rewritten. main had already moved (#86 landed on top) and other sessions branch from it, so force-pushing to regroup eight commits' files would cost more than the defect is worth.

The substance was never wrong. STATUS, BENCHMARKS and FEATURES on main all describe the shipped Vulkan state accurately, with the llvmpipe-only and no-speed-number caveats intact. What was violated is the per-commit granularity that keeps a bisect landing on a commit whose docs match its code, and stops a half-landed series from leaving the public surface describing something that doesn't exist.

Recorded in the state log rather than quietly left, since that range stays permanently gate-failed.

Unrelated pre-existing red

agent-record was already failing on main at 4cfeee13, before the #80 merge — check-fusion-consistency on minimax_h3_video_vae_device. Verified on origin/main itself. Not from this work, and not addressed here.

🤖 Generated with Claude Code