From d2beb5bc0d7fa4eadcfb091ff19e50fd99f2a0a5 Mon Sep 17 00:00:00 2001
From: PurHur <PurHur@users.noreply.github.com>
Date: Mon, 25 May 2026 00:38:25 +0000
Subject: [PATCH] Docs: sync examples/README post-#764 + drift guard (#1531,
 #1822)

Mark 003-MiniWebApp native execute green in the run matrix, add
check-examples-readme-sync.php (opt-in EXAMPLES_README_SYNC_GATE), and flip
ExamplesReadmeTest away from stale empty-stdout wording.

Fixes #1531, #1822

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 examples/README.md                    |  6 +--
 script/check-examples-readme-sync.php | 64 +++++++++++++++++++++++++++
 script/ci-common.sh                   |  9 ++++
 script/ci-docker-run.sh               |  1 +
 test/unit/ExamplesReadmeSyncTest.php  | 22 +++++++++
 test/unit/ExamplesReadmeTest.php      |  6 ++-
 6 files changed, 104 insertions(+), 4 deletions(-)
 create mode 100755 script/check-examples-readme-sync.php
 create mode 100644 test/unit/ExamplesReadmeSyncTest.php

diff --git a/examples/README.md b/examples/README.md
index 90702cbca47..5652b238c76 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -38,7 +38,7 @@ Legacy entrypoints still work: `php bin/vm.php`, `php bin/jit.php`, `php bin/com
 | [001-SimpleWeb](001-SimpleWeb/) | ✅ `-q` / `-p` / env / `phpc serve` | ✅ `bin/jit.php` | ✅ `phpc build` | runtime `QUERY_STRING` / POST ([#201](https://github.com/PurHur/php-compiler/issues/201), [#257](https://github.com/PurHur/php-compiler/issues/257), [#259](https://github.com/PurHur/php-compiler/issues/259)) |
 | [002-StaticWeb](002-StaticWeb/) | ✅ `./phpc run` | ✅ `bin/jit.php` | ✅ recommended | no superglobals — [#247](https://github.com/PurHur/php-compiler/issues/247) execute smoke |
 | [004-ApiJson](004-ApiJson/) | ✅ `./phpc run` | ✅ `bin/jit.php` | ✅ `phpc build` | JSON + `http_response_code` — [#270](https://github.com/PurHur/php-compiler/issues/270), [#61](https://github.com/PurHur/php-compiler/issues/61) |
-| [003-MiniWebApp](003-MiniWebApp/) | ✅ `phpc serve` | partial | ✅ `phpc build --project` | PATH_INFO — [#489](https://github.com/PurHur/php-compiler/issues/489), runtime [#539](https://github.com/PurHur/php-compiler/issues/539); AOT link ✅ ([#752](https://github.com/PurHur/php-compiler/issues/752)); native execute 📋 ([#764](https://github.com/PurHur/php-compiler/issues/764)) |
+| [003-MiniWebApp](003-MiniWebApp/) | ✅ `phpc serve` | partial | ✅ `phpc build --project` | PATH_INFO — [#489](https://github.com/PurHur/php-compiler/issues/489), runtime [#539](https://github.com/PurHur/php-compiler/issues/539); AOT link ✅ ([#752](https://github.com/PurHur/php-compiler/issues/752)); native execute ✅ ([#764](https://github.com/PurHur/php-compiler/issues/764) closed) |
 
 ### 000-HelloWorld
 
@@ -71,7 +71,7 @@ AOT binaries refresh `$_GET` / `$_POST` / `$_REQUEST` from CGI env on each reque
 
 ### 003-MiniWebApp
 
-Reference front controller with PATH_INFO routes ([#489](https://github.com/PurHur/php-compiler/issues/489)). VM serve and `examples-web-smoke.sh` curls are green. `phpc build --project` **links** when LLVM is available ([#752](https://github.com/PurHur/php-compiler/issues/752)); native **execute** still returns empty stdout until [#764](https://github.com/PurHur/php-compiler/issues/764) (`ExamplesCompileTest` documents the gap).
+Reference front controller with PATH_INFO routes ([#489](https://github.com/PurHur/php-compiler/issues/489)). VM serve and `examples-web-smoke.sh` curls are green. `phpc build --project` **links** when LLVM is available ([#752](https://github.com/PurHur/php-compiler/issues/752)); native **execute** is green ([#764](https://github.com/PurHur/php-compiler/issues/764) closed — `MiniWebAppAotExecuteTest`, `make miniwebapp-gates`).
 
 ```console
 ./phpc lint --all examples/003-MiniWebApp
@@ -120,7 +120,7 @@ Before a PR that touches examples or `bin/serve.php`:
 ```console
 make web-smoke              # lint examples/*/example.php + 003 lint --all + VM ?name= smoke
 make examples-web-smoke     # phpc serve + curl GET/POST (001-SimpleWeb, 002-StaticWeb, 004-ApiJson)
-make examples-aot-smoke     # phpc build + CLI execute (000–004; skips when LLVM missing; 003 execute #764)
+make examples-aot-smoke     # phpc build + CLI execute (000–004; skips when LLVM missing; 003 execute green #764)
 ```
 
 Full CI (`./script/ci-local.sh`) runs `examples-aot-smoke.sh` after PHPUnit `@group aot-link` when LLVM is available (`EXAMPLES_AOT_SMOKE_GATE=1` default in `script/ci-defaults.env`; set `EXAMPLES_AOT_SMOKE_GATE=0` to skip during iteration — [#674](https://github.com/PurHur/php-compiler/issues/674)). Not run in `ci-fast.sh`.
diff --git a/script/check-examples-readme-sync.php b/script/check-examples-readme-sync.php
new file mode 100755
index 00000000000..67af66ac7e4
--- /dev/null
+++ b/script/check-examples-readme-sync.php
@@ -0,0 +1,64 @@
+#!/usr/bin/env php
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Guard examples/README.md against stale MiniWebApp execute wording (issues #1822, #1531).
+ *
+ * Fails when known post-#764 phrases remain while native execute is default-on in CI.
+ *
+ * Usage:
+ *   php script/check-examples-readme-sync.php
+ */
+
+$root = dirname(__DIR__);
+$readme = $root.'/examples/README.md';
+$truth = $root.'/examples/003-MiniWebApp/README.md';
+
+if (!is_readable($readme)) {
+    fwrite(STDERR, "check-examples-readme-sync: missing {$readme}\n");
+    exit(1);
+}
+
+$body = (string) file_get_contents($readme);
+
+/** Phrases that imply #764 execute is still open. */
+$stale = [
+    'empty stdout until [#764]',
+    'empty stdout until #764',
+    'execute still returns empty stdout',
+    'native execute 📋',
+    'execute blocked',
+    'blocked #764',
+    'until [#764](https://github.com/PurHur/php-compiler/issues/764)',
+];
+
+$errors = [];
+foreach ($stale as $phrase) {
+    if (str_contains($body, $phrase)) {
+        $errors[] = "stale phrase in examples/README.md: {$phrase}";
+    }
+}
+
+if (!preg_match('/native execute\s*✅/u', $body)) {
+    $errors[] = 'examples/README.md: run matrix should mark 003 native execute ✅ (post-#764)';
+}
+
+if (is_readable($truth)) {
+    $mini = (string) file_get_contents($truth);
+    if (str_contains($mini, 'native execute ✅') && !str_contains($body, 'native execute ✅')) {
+        $errors[] = 'examples/README.md: out of sync with 003-MiniWebApp/README.md (execute status)';
+    }
+}
+
+if ([] !== $errors) {
+    foreach ($errors as $err) {
+        fwrite(STDERR, "check-examples-readme-sync: {$err}\n");
+    }
+    fwrite(STDERR, "check-examples-readme-sync: FAILED (fix examples/README.md; see #1531)\n");
+    exit(1);
+}
+
+fwrite(STDOUT, "check-examples-readme-sync: OK\n");
+exit(0);
diff --git a/script/ci-common.sh b/script/ci-common.sh
index 5395b2ed96c..a2ac02ee41d 100644
--- a/script/ci-common.sh
+++ b/script/ci-common.sh
@@ -87,6 +87,14 @@ ci_run_m2_spine_issue_hygiene_check() {
   "$PHP_BIN" "${PHP_OPTS[@]}" script/check-m2-spine-issue-hygiene.php
 }
 
+ci_run_examples_readme_sync_check() {
+  if [[ "${EXAMPLES_README_SYNC_GATE:-0}" != "1" ]]; then
+    return 0
+  fi
+  echo "Examples README sync (EXAMPLES_README_SYNC_GATE=1, issue #1822)..."
+  "$PHP_BIN" "${PHP_OPTS[@]}" script/check-examples-readme-sync.php
+}
+
 ci_run_inventory_checks() {
   script/check-no-unlimited-memory.sh
   script/check-stale-issue-refs.sh
@@ -97,6 +105,7 @@ ci_run_inventory_checks() {
   ci_ensure_generated_doc script/bootstrap-profile.php docs/bootstrap-profile.json
   ci_run_wave3_roadmap_sync_check
   ci_run_m2_spine_issue_hygiene_check
+  ci_run_examples_readme_sync_check
 }
 
 ci_llvm_dir() {
diff --git a/script/ci-docker-run.sh b/script/ci-docker-run.sh
index 342fddd502b..08383c027e6 100755
--- a/script/ci-docker-run.sh
+++ b/script/ci-docker-run.sh
@@ -18,5 +18,6 @@ ci_docker_run() {
     -e "JIT_PREFLIGHT_GATE=${JIT_PREFLIGHT_GATE:-}" \
     -e "WAVE3_ROADMAP_SYNC_GATE=${WAVE3_ROADMAP_SYNC_GATE:-0}" \
     -e "M2_SPINE_ISSUE_HYGIENE_GATE=${M2_SPINE_ISSUE_HYGIENE_GATE:-1}" \
+    -e "EXAMPLES_README_SYNC_GATE=${EXAMPLES_README_SYNC_GATE:-0}" \
     "$@"
 }
diff --git a/test/unit/ExamplesReadmeSyncTest.php b/test/unit/ExamplesReadmeSyncTest.php
new file mode 100644
index 00000000000..879c7f91b73
--- /dev/null
+++ b/test/unit/ExamplesReadmeSyncTest.php
@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPCompiler;
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * examples/README.md drift guard (issues #1822, #1531).
+ */
+final class ExamplesReadmeSyncTest extends TestCase
+{
+    public function testExamplesReadmeSyncPassesOnMaster(): void
+    {
+        $root = dirname(__DIR__, 2);
+        $cmd = escapeshellarg(PHP_BINARY).' '
+            .escapeshellarg($root.'/script/check-examples-readme-sync.php').' 2>&1';
+        exec($cmd, $out, $code);
+        $this->assertSame(0, $code, implode("\n", $out));
+    }
+}
diff --git a/test/unit/ExamplesReadmeTest.php b/test/unit/ExamplesReadmeTest.php
index ec0ea107abc..464753c56f1 100644
--- a/test/unit/ExamplesReadmeTest.php
+++ b/test/unit/ExamplesReadmeTest.php
@@ -32,7 +32,7 @@ public function testRunMatrixDocumentsPhpcFirst(): void
         $this->assertStringContainsString('make test-docker', $readme);
     }
 
-    public function testMiniWebAppAotStatusReflectsLinkGreenExecute764(): void
+    public function testMiniWebAppAotStatusReflectsLinkAndExecuteGreen(): void
     {
         $root = dirname(__DIR__, 2);
         $readme = (string) file_get_contents($root.'/examples/README.md');
@@ -41,11 +41,15 @@ public function testMiniWebAppAotStatusReflectsLinkGreenExecute764(): void
         foreach ([$readme, $mini] as $body) {
             $this->assertStringNotContainsString('blocked #568', $body);
             $this->assertStringNotContainsString('❌ blocked', $body);
+            $this->assertStringNotContainsString('empty stdout until', $body);
+            $this->assertStringNotContainsString('native execute 📋', $body);
         }
 
+        $this->assertStringContainsString('native execute ✅', $readme);
         $this->assertStringContainsString('#764', $readme);
         $this->assertStringContainsString('phpc build --project', $readme);
         $this->assertStringContainsString('AOT link', $mini);
+        $this->assertStringContainsString('native execute ✅', $mini);
         $this->assertStringContainsString('#764', $mini);
     }
 }