Tooling: doc-sync drift keeps landing on master — add seconds-fast pre-merge drift check (script/check-generated-docs.sh) #15621

Category

tooling · merge-gate DevEx

Problem

Generated-doc drift (docs/capabilities.md, inventory headers, lock content-hash) repeatedly lands on master because the checks live inside ./phpc test --fast (~minutes, often skipped for "docs-only"/"gate-only" merges) and remote CI is disabled (#394). Latest instances: #15619 (capabilities matrix, twice via #15577 + #15591) and #15620 (composer.lock).

The drift checks themselves are cheap; they are just not runnable as a standalone seconds-fast gate.

Proposal

Add script/check-generated-docs.sh bundling only the drift checks (no PHPUnit, no linking):

• php script/capability-matrix.php --check
• php script/capability-syntax.php --check (if applicable)
• php script/bootstrap-inventory.php --check
• composer validate --no-check-publish (lock content-hash)

Target < 30 s so every PR — including docs-only and advertisement-gate PRs — can run it pre-merge. Wire it:

• first step of ./phpc test --fast (already mostly true) and
• documented one-liner in CONTRIBUTING "Before you merge" + agent workflow docs

Done when

• script/check-generated-docs.sh exists, < 30 s, exit 1 on any drift
• CONTRIBUTING + docs/bootstrap-dev-workflow.md reference it as mandatory pre-merge
• Running it on the Foundation: master fast gate red — docs/capabilities.md stale after #15577/#15591 (script/capability-matrix.php) #15619/Foundation: composer.lock content-hash stale after php-parser constraint widen — fresh-clone install warns/fails in pinned env (composer.json) #15620 states reproduces both failures