CI: DOCTOR_GATES_MATRIX_SYNC_GATE — drift guard for phpc doctor --gates vs ci-defaults.env

[PurHur]

Problem

phpc doctor --gates is the presenter-facing ladder for example web smokes and bootstrap probes (#1752, #1903, #2010, #2102), but new env vars land in script/ci-defaults.env + docs/local-ci-matrix.md without a mechanical check that doctor output still lists them.

Gate drift causes “CI failed on FOO_GATE” while phpc doctor --gates omits FOO, wasting contributor time on harness hosts.

Goal

1. script/check-doctor-gates-sync.php — parse ci-defaults.env export *_GATE= names (or curated allowlist file) and assert each appears in lib/Doctor.php gate listing or documented opt-out list in docs/local-ci-matrix.md
2. DOCTOR_GATES_MATRIX_SYNC_GATE=1 default in script/ci-fast.sh inventory checks (opt-out =0 for doctor-only edits)
3. test/unit/DoctorGatesSyncTest.php — fails with actionable diff when drift detected

Implementation hints

Piece	Path	Notes
Checker	script/check-doctor-gates-sync.php	Mirror check-wave3-roadmap-sync.php / check-bootstrap-inventory-triage-sync.php exit codes
Parse SSOT	script/ci-defaults.env	Regex: ^export ([A-Z0-9_]+_GATE)=
Doctor	lib/Doctor.php	Grep listGate / table rows for env var substring
Matrix	docs/local-ci-matrix.md	Backtick gate name in table counts as documented
Allowlist	docs/doctor-gates-allowlist.txt (optional)	Internal-only gates: WAVE3_ROADMAP_SYNC_GATE, PHP_COMPILER_SKIP_SERVE_TESTS, …
CI	script/ci-common.sh	ci_run_inventory_checks() next to #1802 / #2265
Test	test/unit/DoctorGatesSyncTest.php	Shell out to checker or unit-test parser

v1 gate name patterns (include)

• *_SMOKE_GATE, *_SYNC_GATE, BOOTSTRAP_*_GATE, MINIWEBAPP_*_GATE, THROWSWEB_*_GATE, FASTCGI_*_GATE, SERVE_*_GATE

v1 exclusions (allowlist)

• Gates only used inside ci-local.sh without presenter visibility (document why in allowlist file)
• Deprecated aliases (e.g. never-shipped THROWSWEB_WEB_SMOKE_GATE — use THROWS_WEB_SMOKE_GATE)

Regen / fix workflow

php script/check-doctor-gates-sync.php
# add missing rows to lib/Doctor.php + docs/local-ci-matrix.md
./script/ci-fast.sh

Harness:

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php script/check-doctor-gates-sync.php'

Acceptance criteria

• Checker passes on master
• Adding a new export EXAMPLE_FOO_GATE without doctor/matrix entry fails ci-fast when gate enabled
• DOCTOR_GATES_MATRIX_SYNC_GATE=0 skips for iteration
• ROADMAP 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 de-dupe table lists this as canonical doctor drift guard

Verification (local / Docker only)

./script/ci-fast.sh
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit --filter DoctorGatesSync'
make test-harness

No GitHub Actions (#394 ✅).

Dependencies

• DevEx: phpc doctor --gates refresh after North Star 1 default-on gate flips (#1523, #1530) #1752 — doctor --gates baseline
• Docs: Local CI matrix (host, Docker, GHA skips) in README #245 — local CI matrix doc
• Parallel drift guards: CI: Wave 3 roadmap drift guard (docs/roadmap-wave3.md vs #1380) #1802, CI: ROOT_README_008_SYNC_GATE — drift guard for README 008-SelfHostProbe row #2229, Docs: ROOT_README_009 + DEVELOPMENT_STATUS_009 sync drift gates #2353, CI: BOOTSTRAP_INVENTORY_TRIAGE_DRIFT_GATE opt-in after #2254 #2265

Links

• ROADMAP 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 Phase 4 Polish · docs/local-ci-matrix.md