DevEx: make north-star2-verify presenter gate (self-host M0–M4)

[PurHur]

Problem

North Star 1 has a single presenter entry point (#1845 make north-star1-verify, phpc doctor --gates). North Star 2 (#1492) still requires contributors to remember a scattered ladder:

• php script/bootstrap-inventory.php --check
• make bootstrap-wave-check / BOOTSTRAP_LIB_SPINE_SMOKE=1 make bootstrap-selfhost-lib-spine-smoke
• BOOTSTRAP_LIB_SPINE_VM_SMOKE=1 make bootstrap-selfhost-lib-spine-vm-smoke (#1846)
• BOOTSTRAP_M3_HELLOWORLD_STRICT=1 ./script/bootstrap-selfhost-helloworld-probe.sh (#1493)
• BOOTSTRAP_LOOP_PROBE_GATE=1 ./script/bootstrap-loop-probe.sh --dry-run (#1498)

Before M3/M4 milestones close, there is no one command for demos or pre-merge self-host sanity.

Scope

1. Add script/north-star2-verify.sh + make north-star2-verify mirroring #1845 structure:
   • Step 1: phpc doctor --gates (or dedicated --selfhost flag) — list self-host env vars
   • Step 2: inventory --check (#765)
   • Step 3: bootstrap-wave-check (M0–M2 probes)
   • Step 4 (LLVM): spine native link + VM -r smoke (#1846)
   • Step 5 (LLVM, opt-in tail): M3 strict probe + M4 loop --dry-run
2. Flags: --require-llvm, --skip-llvm-tail (same UX as north-star1)
3. test/unit/NorthStar2VerifyScriptTest.php asserts script + Makefile wiring
4. Document in docs/bootstrap-selfhost.md, docs/GETTING-STARTED.md, README North Star 2 section

Out of scope: flipping BOOTSTRAP_M3_HELLOWORLD_STRICT_GATE default-on — tracked in #1866.

Acceptance criteria

• make north-star2-verify exits 0 on harness with LLVM 9 (Docker php-compiler:22.04-dev)
• Without LLVM, runnable steps pass and LLVM tail is skipped with clear message
• phpc doctor --gates mentions make north-star2-verify (extend DevEx: phpc doctor --gates lists north-star1-verify presenter steps (#1845 phase 2) #1857](DevEx: phpc doctor --gates lists north-star1-verify presenter steps (#1845 phase 2) #1857) pattern for NS2)
• ROADMAP 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 links this issue under Phase 5

Dependencies

• Self-host M2: land final 3 ext/standard Vm* units in compiler_lib_spine_smoke (578→586) #1821 — spine 584→586 (step 4 should not fail on missing Vm* units)
• M3: BOOTSTRAP_M3_HELLOWORLD_STRICT — native HelloWorld emit (no Zend fallback) #1493 — M3 strict step meaningful after native emit path green
• Orthogonal: 🌐 North Star 1: Web-capable PHP application (living tracker) #1044 ✅ (NS1 achieved)

Verify (local / Docker only)

make docker-build-22
docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev make north-star2-verify
# Without LLVM on host:
make north-star2-verify   # expects skip message for LLVM tail

Do not require GitHub Actions. Optional cloud mirror only per #394 policy.

Links

• Epic: Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492
• ROADMAP: 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78
• NS1 presenter: DevEx: make north-star1-verify presenter gate before #1044 close #1845
• docs/self-host-target.md

[PurHur]

Dependency update (batch 78): #1821 ✅ closed — spine step 4 in north-star2-verify should not block on Vm* units. Spine count truth: #1872. Doctor listing: #1871.

[PurHur]

Implementation hints (batch 88 — expand)

Mirror script/north-star1-verify.sh (#1845) structure. Suggested files:

Step	Command / script	LLVM?	Issue
0	./phpc doctor --gates (self-host section from #1871)	no	#1903 adds 005 ladder
1	php script/bootstrap-inventory.php --check	no	#765
2	make bootstrap-wave-check	no	M0–M2
3	BOOTSTRAP_LIB_SPINE_SMOKE=1 make bootstrap-selfhost-lib-spine-smoke	yes	#1880 ✅
4	BOOTSTRAP_LIB_SPINE_VM_SMOKE=1 make bootstrap-selfhost-lib-spine-vm-smoke	yes	#1875 ✅
5	BOOTSTRAP_M3_HELLOWORLD_STRICT=1 ./script/bootstrap-selfhost-helloworld-probe.sh	yes	#1493
6 (opt-in)	BOOTSTRAP_LOOP_PROBE_GATE=1 ./script/bootstrap-loop-probe.sh --dry-run	yes	#1498

script/north-star2-verify.sh sketch

source "$(dirname "$0")/ci-common.sh"
ci_cd_repo
./phpc doctor --gates || exit 1
php script/bootstrap-inventory.php --check || exit 1
make bootstrap-wave-check || exit 1
if ci_llvm_ready; then
  BOOTSTRAP_LIB_SPINE_SMOKE=1 make bootstrap-selfhost-lib-spine-smoke
  BOOTSTRAP_LIB_SPINE_VM_SMOKE=1 make bootstrap-selfhost-lib-spine-vm-smoke
  BOOTSTRAP_M3_HELLOWORLD_STRICT=1 ./script/bootstrap-selfhost-helloworld-probe.sh
else
  echo "north-star2-verify: LLVM steps skipped (use --require-llvm to fail)"
fi

Makefile

north-star2-verify:
	./script/north-star2-verify.sh

Doctor integration (#1871)

Add block after NS1 steps in lib/Cli/PhpcDoctor.php listing BOOTSTRAP_* env vars and make north-star2-verify.

Verify (no GHA)

make docker-build-22
make north-star2-verify
# or:
docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev make north-star2-verify

Depends on: #1493 for step 5 to pass strict emit; steps 1–4 can pass today on LLVM hosts.

[PurHur]

Implementation hints (batch 98 — script skeleton)

ci-fast.sh already calls ci_run_north_star2_verify() and skips when script/north-star2-verify.sh is missing (#1928). This issue delivers that script + Makefile target.

Suggested script/north-star2-verify.sh steps

Step	Command	LLVM?	Gate env
0	./phpc doctor --gates (self-host section)	no	—
1	php script/bootstrap-inventory.php --check	no	—
2	./script/bootstrap-wave-check.sh	partial	skips link if no LLVM
3	BOOTSTRAP_LIB_SPINE_SMOKE=1 make bootstrap-selfhost-lib-spine-smoke	yes	opt-in tail
4	BOOTSTRAP_LIB_SPINE_VM_SMOKE=1 make bootstrap-selfhost-lib-spine-vm-smoke	yes	#1867
5	BOOTSTRAP_M3_HELLOWORLD_STRICT=1 ./script/bootstrap-selfhost-helloworld-probe.sh	yes	#1493 ✅
6	BOOTSTRAP_M3_COMPILE_SMOKE_STRICT=1 ./script/bootstrap-selfhost-compile-smoke-probe.sh	yes	#1977 / #1983
7	BOOTSTRAP_LOOP_PROBE_GATE=1 ./script/bootstrap-loop-probe.sh --dry-run	yes	#1498

Flags:

• --skip-llvm-tail — steps 3–7 skipped (for ci-fast / hosts without .llvm/)
• --require-llvm — fail if LLVM missing when tail requested

Files to add/change

Path	Notes
script/north-star2-verify.sh	Mirror script/north-star1-verify.sh structure
Makefile	north-star2-verify target
docs/GETTING-STARTED.md	Table row (optional #1958-adjacent)
lib/Doctor.php	Already references script path — flips from pending to ✅
test/unit/NorthStar2VerifyTest.php	Assert script exists + --help or dry-run exit 0

Follow-ups (separate issues)

• CI: NORTH_STAR2_VERIFY_GATE opt-in in ci-fast after #1865 #1928 — NORTH_STAR2_VERIFY_GATE=1 opt-in in ci-fast
• Default-on gate after M3 stable (CI: Default BOOTSTRAP_M3_HELLOWORLD_STRICT_GATE=1 in ci-local after #1493 #1866 pattern)

Verification

make north-star2-verify --skip-llvm-tail   # or script flag
make north-star2-verify                    # full, needs LLVM 9
docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev make north-star2-verify

Canonical CI remains ./script/ci-local.sh / make test-docker (#436, #245) — not GHA.

[PurHur]

Landed in #2046: make north-star2-verify / ./script/north-star2-verify.sh with --require-llvm, --skip-llvm-tail, --strict. Wired in phpc doctor --gates and opt-in NORTH_STAR2_VERIFY_GATE=1 in ci-fast.