DevEx: MiniWebApp CI gate ladder (lint → serve → AOT → web-smoke)

[PurHur]

Problem

examples/003-MiniWebApp/ needs a progressive gate ladder so contributors know which env vars are on by default vs opt-in. Stages 0–3 are default-on in full CI.

Batch 50 (2026-05-23): Stage 4b link is green on Docker harness. Stage 4b2 execute is the active blocker (#764). Stages 4c–4d remain blocked on execute + HTTP.

Gate ladder

Stage	Env / target	Default on master	Tracking
0 Skeleton	MINIWEBAPP_LINT_GATE=0	opt-out only	#621 ✅
1 Lint	MINIWEBAPP_LINT_GATE=1	✅ web-smoke.sh	#539, #621
1b VM CLI	MINIWEBAPP_VM_CLI_GATE=1	✅ ci-fast.sh	#597, #595
2 Serve PHPUnit	MINIWEBAPP_SERVE_GATE=1	✅ ci-local.sh / ci-fast.sh	#641 ✅
3 Shell web-smoke	MINIWEBAPP_WEB_SMOKE_GATE=1	✅ ci-local.sh	#664 ✅
4a AOT dry-run	phpc build --project --dry-run	@group aot-lint	#624, #675
4b AOT link	phpc build --project exit 0	✅ #752 ✅	#754 policy
4b2 AOT execute	CLI env → non-empty HTML	❌	#764, #747, #485
4c AOT shell smoke	examples-aot-smoke 003 slice	❌	#738
4d AOT HTTP	ServeAotTest + phpc serve --aot	❌	#478, #610
4e Deploy smoke	make deploy-smoke 003	❌	#745, #612

Scope

• README tables in examples/003-MiniWebApp/README.md
• script/miniwebapp-gates.sh + make miniwebapp-gates + phpc doctor --gates (DevEx: phpc doctor --gates prints MiniWebApp ladder status #657 ✅)
• Promote stage 2–3 default (CI: Default MINIWEBAPP_SERVE_GATE=1 in ci-local.sh (promote gate ladder stage 2) #641, CI: Default MINIWEBAPP_WEB_SMOKE_GATE=1 in ci-local.sh (promote gate ladder stage 3) #664 ✅)
• Stage 4b link green (AOT: MiniWebApp phpc build --project native link fails on master (post-#568/#734) #752 ✅, batch 50 verify)
• Stage 4b2 in miniwebapp-gates.sh + doctor (AOT: MiniWebApp native binary CLI execute emits empty stdout (post-link) #764, DevEx: phpc doctor --aot-project-probe for MiniWebApp #746 probe)
• Stage 4c–4e when Testing: MiniWebApp AOT unskip matrix after #568 (orchestrate #454 #485 #478 #610) #676 steps 3–6 land
• Close when stage 4d default-on in ci-local.sh

Implementation hints

Piece	File	Change
Gates script	script/miniwebapp-gates.sh	Add stage 4b2: run .phpc/bin/app with QUERY_STRING=route=home, fail if stdout empty
Doctor	lib/Doctor.php	Print 4b ✅ / 4b2 ❌ with issue links
CI env	script/ci-defaults.env	MINIWEBAPP_AOT_EXECUTE_GATE=0 until #747 green (mirror #754 link gate)
Docs	examples/003-MiniWebApp/README.md	Replace “blocked #568” with #764

# Manual 4b2 probe (batch 50):
composer install && ./script/apply-patches.sh
php bin/phpc.php build --project examples/003-MiniWebApp
cd examples/003-MiniWebApp && QUERY_STRING=route=home REQUEST_METHOD=GET ./.phpc/bin/app | wc -c
# expect >0; currently 0 → #764

Acceptance criteria

./script/miniwebapp-gates.sh      # stages 0–4b pass; 4b2 fails until #764 fixed
./phpc doctor --gates

Docker:

docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev ./script/miniwebapp-gates.sh

Dependencies

• Reference app: MiniWebApp runtime green (lint 0, VM serve, routes) #539 ✅ VM
• AOT: MiniWebApp phpc build --project native link fails on master (post-#568/#734) #752 ✅ link
• AOT: MiniWebApp native binary CLI execute emits empty stdout (post-link) #764 — execute
• Testing: MiniWebApp AOT unskip matrix after #568 (orchestrate #454 #485 #478 #610) #676 matrix
• DevEx: Retire #568 user-class blocker copy in PhpcBuild and tests #766 — copy cleanup

Links

• DevEx: make miniwebapp-gates — print MiniWebApp CI gate ladder status #503, 🗺️ ROADMAP: Compile a small PHP web application (living document) #78, CI: Default EXAMPLES_AOT_SMOKE_GATE=1 in ci-local.sh (promote #667) #674, Testing: ExamplesCompileTest 003 link gate policy (link green; execute #764) #754

[PurHur]

Doc fix (batch 27): Gate ladder stage 2 Serve PHPUnit should reference #470 (VM ServeMiniWebAppTest), not #464 (unrelated AOT ?? lowering).

Stage 4 AOT serve gate: #478 (ServeAotTest MiniWebApp routes).

[PurHur]

Gate-ladder UX split: #503 () implements the printable status table from this issue's scope checklist.

[PurHur]

Batch 31 status: #503 ✅ shipped make miniwebapp-gates / script/miniwebapp-gates.sh. Remaining scope from this issue:

• examples/003-MiniWebApp/README.md — document MINIWEBAPP_SERVE_GATE=1 next to Testing: ServeTest MiniWebApp routes via phpc serve (skipped until #67) #470
• script/web-smoke.sh — honor MINIWEBAPP_SERVE_GATE (fail or explicit skip message)
• Link Reference app: MiniWebApp runtime green (lint 0, VM serve, routes) #539 as runtime-green tracker ( Reference app: examples/003-MiniWebApp (router, templates, forms) #67 closed = skeleton only )

Consider closing checklist items as docs land; keep open until MINIWEBAPP_SERVE_GATE is wired.

[PurHur]

CI de-duplication (batch 32)

#472 documents the MiniWebApp gate ladder (lint → serve → AOT → web-smoke). It does not replace the repo-wide CI entrypoints:

Gate	Command	Issue
Full (VM+JIT+AOT+serve)	./script/ci-local.sh, make test-docker	#46, #436
Fast (VM/compliance)	./script/ci-fast.sh, make test-fast	#436 ✅
MiniWebApp status print	make miniwebapp-gates	#503 ✅
003 lint in fast CI	PhpcLintProjectTest	#570

Harness: make test-harness when bind-mount is empty (#272). No GHA required.