Close Level 24 with a real execution-backed guard.

Add one runnable validation entry point that enforces:
- roadmap lock rules
- fullscreen restriction to sample 0713

No roadmap edits.
No engine changes.
No gameplay changes.

PR: BUILD_PR_LEVEL_24_5_PHASE_24_CLOSEOUT_EXECUTION_GUARD

Author: DavidQ

docs/dev/reports/BUILD_PR_LEVEL_24_5_PHASE_24_CLOSEOUT_EXECUTION_GUARD_REPORT.txt

@@ -0,0 +1,21 @@
+BUILD_PR_LEVEL_24_5 Phase 24 Closeout Execution Guard Report
+
+Command
+- npm run check:phase24-closeout-guard
+
+Result
+- PASS
+- PHASE24_CLOSEOUT_EXECUTION_GUARD_PASS
+- Roadmap lock path: docs/dev/roadmaps/MASTER_ROADMAP_ENGINE.md
+- Fullscreen sample hits: 2
+- Fullscreen outside allowed root: 0
+
+Guard entry point
+- package.json script: check:phase24-closeout-guard
+- runtime: tools/dev/checkPhase24CloseoutExecutionGuard.mjs
+- baseline: tools/dev/checkPhase24CloseoutExecutionGuard.baseline.json
+
+Scope notes
+- No roadmap text/status edits
+- No engine changes
+- No gameplay changes

docs/dev/reports/phase_24_closeout_execution_guard_spec.txt

@@ -0,0 +1,21 @@
+Phase 24 Closeout Execution Guard Spec
+
+Goal:
+End Level 24 with a real runnable guard, not a commit-only or status-only tail.
+
+Required checks:
+1. Roadmap file path remains:
+   docs/dev/roadmaps/MASTER_ROADMAP_ENGINE.md
+2. Roadmap lock policy remains enforced:
+   - allow only [ ] -> [.]
+   - allow only [.] -> [x]
+   - reject all non-status edits
+   - reject file replacement/rename
+3. Fullscreen policy remains enforced:
+   - allow fullscreen only in samples/phase-07/0713
+   - fail on any hit outside 0713
+
+Suggested outputs:
+- PASS/FAIL summary
+- offending file list when failing
+- non-zero exit on failure

docs/dev/reports/validation_checklist.txt

@@ -1,7 +1,11 @@
 Validation Checklist
 
-[x] API lock validated
-[x] Boundaries validated
-[x] Contracts documented
-[x] Docs cleanup verified
-[x] Status-only roadmap update applied
+[x] Runnable guard added
+[x] Guard executes in one pass from repo root
+[x] Roadmap file path lock checked
+[x] Roadmap non-status edit lock checked
+[x] Fullscreen outside 0713 checked
+[x] Clear PASS/FAIL output produced
+[x] No roadmap text edits made
+[x] No engine changes made
+[x] No gameplay changes made

docs/pr/BUILD_PR_LEVEL_24_5_PHASE_24_CLOSEOUT_EXECUTION_GUARD.md

@@ -0,0 +1,69 @@
+# BUILD_PR_LEVEL_24_5_PHASE_24_CLOSEOUT_EXECUTION_GUARD
+
+## Purpose
+Close Level 24 with one small, testable, execution-backed PR.
+
+This replaces the prior non-executable `24_5` planning stub.
+No roadmap advancement happens in this PR.
+No commit-only packaging.
+No roadmap text edits.
+
+## Why this PR is needed
+Phase 24 roadmap items are already complete.
+What is missing is a final executable guard so Phase 24 ends on a testable artifact rather than a docs-only/status-only tail.
+
+## Single PR Purpose
+Add one runnable guard entry point that checks both of these locked rules:
+1. Roadmap file is locked against non-status edits.
+2. Fullscreen remains restricted to sample `0713`.
+
+## In Scope
+- add one guard script or one guard test entry point
+- make it runnable in one pass from the repo root
+- validate:
+  - roadmap file path is unchanged
+  - roadmap content is not replaced/renamed
+  - fullscreen usage outside `samples/phase-07/0713` fails
+- add minimal documentation for how to run the guard
+- add test/report output under docs/dev/reports if useful
+
+## Out of Scope
+- no roadmap text edits
+- no roadmap status changes
+- no engine changes
+- no gameplay changes
+- no sample feature work
+- no broad repo cleanup
+- no template-driven expansion
+
+## Preferred Implementation Shape
+Choose the smallest executable option already aligned with repo tooling:
+- either a focused Node test
+- or a focused PowerShell validator
+- or both only if one invokes the other and remains one-pass executable
+
+Prefer PowerShell if it reduces Codex token usage.
+
+## Required Behavior
+The guard must fail if any of the following are true:
+- `docs/dev/roadmaps/MASTER_ROADMAP_ENGINE.md` is renamed or replaced
+- roadmap text is rewritten, reordered, added to, deleted from, or reflowed
+- any non-status roadmap edit is detected
+- fullscreen usage exists outside sample `0713`
+
+The guard must pass when:
+- roadmap remains locked
+- only status-marker transitions are allowed in principle
+- fullscreen hits remain limited to the known `0713` files
+
+## Run
+- `npm run check:phase24-closeout-guard`
+
+## Acceptance
+- one-pass executable from repo root
+- testable and repeatable
+- no roadmap edits required
+- no engine/gameplay changes
+- guard clearly reports pass/fail
+- package output to:
+  `<project folder>/tmp/BUILD_PR_LEVEL_24_5_PHASE_24_CLOSEOUT_EXECUTION_GUARD.zip`

package.json

@@ -5,10 +5,11 @@
     "test": "node ./scripts/run-node-tests.mjs",
     "build:manifest": "node ./scripts/generate-sample-manifest.mjs",
     "check:shared-extraction-guard": "node tools/dev/checkSharedExtractionGuard.mjs",
+    "check:phase24-closeout-guard": "node tools/dev/checkPhase24CloseoutExecutionGuard.mjs",
     "check:games-template-contract": "node ./scripts/validate-games-template-contract.mjs",
     "test:launch-smoke": "node ./tests/runtime/LaunchSmokeAllEntries.test.mjs"
   },
   "dependencies": {
     "ws": "^8.20.0"
   }
-}
+}

tools/dev/checkPhase24CloseoutExecutionGuard.baseline.json

@@ -0,0 +1,12 @@
+{
+  "roadmapPath": "docs/dev/roadmaps/MASTER_ROADMAP_ENGINE.md",
+  "statusInsensitiveSha256": "1fb2ead588a71e63291463c04fb012c76749ff929a7ed1b4b3aac015b94dcc16",
+  "fullscreenAllowedRoot": "samples/phase-07/0713",
+  "fullscreenPatterns": [
+    "requestFullscreen",
+    "webkitRequestFullscreen",
+    "engine.fullscreen",
+    "fullscreenPreferred",
+    "settings-fullscreen"
+  ]
+}

tools/dev/checkPhase24CloseoutExecutionGuard.mjs

@@ -0,0 +1,120 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = path.resolve(__dirname, "../..");
+const baselinePath = path.join(__dirname, "checkPhase24CloseoutExecutionGuard.baseline.json");
+
+const SOURCE_EXTENSIONS = new Set([".js", ".mjs", ".cjs", ".html", ".json"]);
+const SKIP_DIRS = new Set(["metadata", "shared", "_shared"]);
+
+function toPosix(value) {
+  return value.replace(/\\/g, "/");
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function sha256(text) {
+  return crypto.createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+function normalizeRoadmapStatusMarkers(roadmapText) {
+  const lf = roadmapText.replace(/\r\n/g, "\n");
+  return lf.replace(/^([ \t]*[-*]?\s*\[)(?: |\.|x)(\])/gm, "$1#$2");
+}
+
+function collectSampleFiles(samplesRoot) {
+  const out = [];
+  const stack = [samplesRoot];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        const isSamplesRootChild = path.resolve(current) === path.resolve(samplesRoot);
+        if (isSamplesRootChild && SKIP_DIRS.has(entry.name)) {
+          continue;
+        }
+        stack.push(full);
+        continue;
+      }
+      if (SOURCE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+        out.push(full);
+      }
+    }
+  }
+  return out;
+}
+
+function runGuard() {
+  if (!fs.existsSync(baselinePath)) {
+    throw new Error(`Missing baseline: ${toPosix(path.relative(repoRoot, baselinePath))}`);
+  }
+
+  const baseline = readJson(baselinePath);
+  const roadmapPath = path.join(repoRoot, baseline.roadmapPath);
+  const errors = [];
+
+  if (!fs.existsSync(roadmapPath)) {
+    errors.push(`Roadmap path missing: ${baseline.roadmapPath}`);
+  } else {
+    const roadmapText = fs.readFileSync(roadmapPath, "utf8");
+    const normalized = normalizeRoadmapStatusMarkers(roadmapText);
+    const hash = sha256(normalized);
+    if (hash !== baseline.statusInsensitiveSha256) {
+      errors.push(
+        `Roadmap non-status drift detected at ${baseline.roadmapPath}. Expected ${baseline.statusInsensitiveSha256}, got ${hash}.`
+      );
+    }
+  }
+
+  const samplesRoot = path.join(repoRoot, "samples");
+  const allowedRoot = path.join(repoRoot, baseline.fullscreenAllowedRoot);
+  const patterns = (baseline.fullscreenPatterns || []).map((token) => ({ token, re: new RegExp(token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g") }));
+  const hitsOutsideAllowed = [];
+  let totalHits = 0;
+
+  for (const filePath of collectSampleFiles(samplesRoot)) {
+    const source = fs.readFileSync(filePath, "utf8");
+    let matched = false;
+    for (const { re } of patterns) {
+      if (re.test(source)) {
+        matched = true;
+      }
+      re.lastIndex = 0;
+    }
+    if (!matched) {
+      continue;
+    }
+    totalHits += 1;
+    if (!path.resolve(filePath).startsWith(path.resolve(allowedRoot))) {
+      hitsOutsideAllowed.push(toPosix(path.relative(repoRoot, filePath)));
+    }
+  }
+
+  if (hitsOutsideAllowed.length > 0) {
+    errors.push(
+      `Fullscreen policy violation outside ${baseline.fullscreenAllowedRoot}:\n- ${hitsOutsideAllowed.join("\n- ")}`
+    );
+  }
+
+  if (errors.length > 0) {
+    console.error("PHASE24_CLOSEOUT_EXECUTION_GUARD_FAIL");
+    errors.forEach((item) => console.error(item));
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log("PHASE24_CLOSEOUT_EXECUTION_GUARD_PASS");
+  console.log(`Roadmap lock path: ${baseline.roadmapPath}`);
+  console.log(`Fullscreen sample hits: ${totalHits}`);
+  console.log(`Fullscreen outside allowed root: 0`);
+}
+
+runGuard();