BUILD_PR_LEVEL_14_TESTS_VALIDATION_COMBINED_PASS

DavidQ · DavidQ · commit 693b87e12b8d · 2026-04-14T21:57:01.000-04:00
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -3,14 +3,13 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create `BUILD_PR_LEVEL_12_2D_CAPABILITY_TRACK_RESIDUE_ONLY`.
+Create BUILD_PR_LEVEL_14_TESTS_VALIDATION_COMBINED_PASS.
 
-1. Inspect prior combined PR results.
-2. Identify remaining open items ONLY.
-3. Apply minimal fixes.
-4. Do not expand scope.
+1. Normalize tests/ structure.
+2. Align unit/integration coverage.
+3. Organize fixtures/helpers.
+4. Align validation with engine/shared/tools.
 5. Update roadmap status markers only.
-6. Report if lane is fully complete.
 
 Package:
-`<project folder>/tmp/BUILD_PR_LEVEL_12_2D_CAPABILITY_TRACK_RESIDUE_ONLY.zip`
+<project folder>/tmp/BUILD_PR_LEVEL_14_TESTS_VALIDATION_COMBINED_PASS.zip
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1 @@
-BUILD_PR_LEVEL_12_2D_CAPABILITY_TRACK_RESIDUE_ONLY
+BUILD_PR_LEVEL_14_TESTS_VALIDATION_COMBINED_PASS
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1 +1 @@
-NEXT_LANE_SELECTION
+BUILD_PR_LEVEL_14_TESTS_VALIDATION_RESIDUE_ONLY
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1 +1 @@
-Residue-only closeout for 2D capability track
+Combined tests/validation normalization pass
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1 +1 @@
-Only remaining items touched; lane complete or blockers listed
+tests normalized, coverage aligned, fixtures organized
diff --git a/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md b/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
@@ -550,11 +550,11 @@
 ---
 
 ## 14. Testing & Validation
-- [.] `tests/` structure normalized
-- [.] unit coverage aligned to engine/shared/games
-- [.] integration coverage aligned to state/replay/rendering/tools
+- [x] `tests/` structure normalized
+- [x] unit coverage aligned to engine/shared/games
+- [x] integration coverage aligned to state/replay/rendering/tools
 - [x] smoke validation aligned to samples/tools/games
-- [.] fixtures/helpers organization normalized
+- [x] fixtures/helpers organization normalized
 - [x] move/refactor validation strategy documented
 - [x] post-PR acceptance criteria consistently enforced
 
diff --git a/docs/pr/BUILD_PR_LEVEL_14_TESTS_VALIDATION_COMBINED_PASS.md b/docs/pr/BUILD_PR_LEVEL_14_TESTS_VALIDATION_COMBINED_PASS.md
@@ -0,0 +1,62 @@
+# BUILD_PR_LEVEL_14_TESTS_VALIDATION_COMBINED_PASS
+
+## Purpose
+Stabilize the tests and validation lane with a single combined pass focused on structure normalization, coverage anchors, fixture/helper organization, and validation alignment.
+
+## Completed Scope
+
+### 1) `tests/` structure normalization
+- Added `tests/helpers/` for shared validation catalogs.
+- Added `tests/fixtures/` with grouped fixture subfolders:
+  - `tests/fixtures/games/`
+  - `tests/fixtures/tools/`
+
+### 2) Unit/integration coverage alignment
+- Added `tests/helpers/testCoverageCatalog.mjs` to define explicit:
+  - required structure directories
+  - unit coverage anchors
+  - integration coverage anchors
+  - fixture artifact inventory
+- Added `tests/production/TestsValidationCombinedPass.test.mjs` to enforce these boundaries.
+- Wired the new test into `tests/run-tests.mjs`.
+
+### 3) Fixture/helper organization
+Moved non-executable fixture artifacts out of executable test folders:
+- `tests/games/AsteroidsValidation.snippet.js` -> `tests/fixtures/games/AsteroidsValidation.snippet.js`
+- `tests/games/AsteroidsValidation.test.mjs.patch` -> `tests/fixtures/games/AsteroidsValidation.test.mjs.patch`
+- `tests/tools/VectorNativeTemplate.regex.before.txt` -> `tests/fixtures/tools/VectorNativeTemplate.regex.before.txt`
+- `tests/tools/VectorNativeTemplate.regex.after.txt` -> `tests/fixtures/tools/VectorNativeTemplate.regex.after.txt`
+- `tests/tools/VectorNativeTemplate.test.mjs.patch` -> `tests/fixtures/tools/VectorNativeTemplate.test.mjs.patch`
+
+### 4) Validation alignment with engine/shared/tools
+`TestsValidationCombinedPass` enforces presence of anchor tests aligned to:
+- engine/core boundary coverage
+- shared foundation coverage
+- tool boundary/integration coverage
+- state/replay/rendering integration coverage
+
+### 5) Roadmap status updates
+Updated status markers only for Section 14:
+- `tests/` structure normalized -> `[x]`
+- unit coverage aligned to engine/shared/games -> `[x]`
+- integration coverage aligned to state/replay/rendering/tools -> `[x]`
+- fixtures/helpers organization normalized -> `[x]`
+
+No roadmap prose rewrite.
+
+## Validation Performed
+- `node --check` on touched JS/MJS files.
+- `tests/production/TestsValidationCombinedPass.test.mjs`
+- `tests/core/EngineCoreBoundaryBaseline.test.mjs`
+- `tests/shared/SharedFoundationCombinedPass.test.mjs`
+- `tests/tools/ToolBoundaryEnforcement.test.mjs`
+- `tests/tools/RuntimeAssetBinding.test.mjs`
+- `tests/replay/ReplaySystem.test.mjs`
+- `tests/replay/ReplayTimeline.test.mjs`
+- `tests/world/WorldGameStateSystem.test.mjs`
+- `tests/render/Renderer.test.mjs`
+
+All focused checks passed.
+
+## Packaging
+<project folder>/tmp/BUILD_PR_LEVEL_14_TESTS_VALIDATION_COMBINED_PASS.zip
diff --git a/tests/README.md b/tests/README.md
@@ -14,3 +14,7 @@ npm test
 - persistence, serialization, FX determinism
 - production/import guardrails for engine barrels
 - game boots and hardening flows (Asteroids plus AI track entry points)
+
+## Structure Notes
+- `tests/helpers/` holds shared test catalogs/helpers used by validation tests.
+- `tests/fixtures/` holds non-executable fixture artifacts (`.patch`, `.snippet`, and regex snapshots) kept out of executable suites.
diff --git a/tests/fixtures/games/AsteroidsValidation.snippet.js b/tests/fixtures/games/AsteroidsValidation.snippet.js
diff --git a/tests/fixtures/games/AsteroidsValidation.test.mjs.patch b/tests/fixtures/games/AsteroidsValidation.test.mjs.patch
diff --git a/tests/fixtures/tools/VectorNativeTemplate.regex.after.txt b/tests/fixtures/tools/VectorNativeTemplate.regex.after.txt
diff --git a/tests/fixtures/tools/VectorNativeTemplate.regex.before.txt b/tests/fixtures/tools/VectorNativeTemplate.regex.before.txt
diff --git a/tests/fixtures/tools/VectorNativeTemplate.test.mjs.patch b/tests/fixtures/tools/VectorNativeTemplate.test.mjs.patch
diff --git a/tests/helpers/testCoverageCatalog.mjs b/tests/helpers/testCoverageCatalog.mjs
@@ -0,0 +1,38 @@
+import path from "node:path";
+
+export const TESTS_ROOT = path.resolve("tests");
+
+export const REQUIRED_TEST_DIRECTORIES = Object.freeze([
+  "core",
+  "shared",
+  "tools",
+  "games",
+  "replay",
+  "world",
+  "render",
+  "fixtures",
+  "helpers",
+  "production"
+]);
+
+export const UNIT_COVERAGE_ANCHORS = Object.freeze([
+  "tests/core/EngineCoreBoundaryBaseline.test.mjs",
+  "tests/shared/SharedFoundationCombinedPass.test.mjs",
+  "tests/tools/ToolBoundaryEnforcement.test.mjs"
+]);
+
+export const INTEGRATION_COVERAGE_ANCHORS = Object.freeze([
+  "tests/world/WorldGameStateSystem.test.mjs",
+  "tests/replay/ReplaySystem.test.mjs",
+  "tests/render/Renderer.test.mjs",
+  "tests/tools/RuntimeAssetBinding.test.mjs",
+  "tests/core/Engine2DCapabilityCombinedFoundation.test.mjs"
+]);
+
+export const FIXTURE_ARTIFACTS = Object.freeze([
+  "tests/fixtures/games/AsteroidsValidation.snippet.js",
+  "tests/fixtures/games/AsteroidsValidation.test.mjs.patch",
+  "tests/fixtures/tools/VectorNativeTemplate.regex.before.txt",
+  "tests/fixtures/tools/VectorNativeTemplate.regex.after.txt",
+  "tests/fixtures/tools/VectorNativeTemplate.test.mjs.patch"
+]);
diff --git a/tests/production/TestsValidationCombinedPass.test.mjs b/tests/production/TestsValidationCombinedPass.test.mjs
@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import {
+  REQUIRED_TEST_DIRECTORIES,
+  UNIT_COVERAGE_ANCHORS,
+  INTEGRATION_COVERAGE_ANCHORS,
+  FIXTURE_ARTIFACTS
+} from "../helpers/testCoverageCatalog.mjs";
+
+const REPO_ROOT = path.resolve(".");
+
+function assertRepoFile(relativePath) {
+  const absolutePath = path.join(REPO_ROOT, relativePath);
+  assert.equal(existsSync(absolutePath), true, `Missing file: ${relativePath}`);
+  assert.equal(statSync(absolutePath).isFile(), true, `Not a file: ${relativePath}`);
+}
+
+function assertRepoDirectory(relativePath) {
+  const absolutePath = path.join(REPO_ROOT, relativePath);
+  assert.equal(existsSync(absolutePath), true, `Missing directory: ${relativePath}`);
+  assert.equal(statSync(absolutePath).isDirectory(), true, `Not a directory: ${relativePath}`);
+}
+
+export function run() {
+  REQUIRED_TEST_DIRECTORIES.forEach((dir) => {
+    assertRepoDirectory(`tests/${dir}`);
+  });
+
+  UNIT_COVERAGE_ANCHORS.forEach((filePath) => {
+    assertRepoFile(filePath);
+  });
+
+  INTEGRATION_COVERAGE_ANCHORS.forEach((filePath) => {
+    assertRepoFile(filePath);
+  });
+
+  FIXTURE_ARTIFACTS.forEach((filePath) => {
+    assertRepoFile(filePath);
+  });
+
+  const runTestsPath = path.join(REPO_ROOT, "tests", "run-tests.mjs");
+  const runTestsText = readFileSync(runTestsPath, "utf8");
+  assert.match(runTestsText, /runTestsValidationCombinedPass/);
+  assert.match(runTestsText, /\['TestsValidationCombinedPass', runTestsValidationCombinedPass\]/);
+}
diff --git a/tests/run-tests.mjs b/tests/run-tests.mjs
@@ -87,6 +87,7 @@ import { run as runWorldGameStateAuthoritativeHandoff } from './world/WorldGameS
 import { run as runWorldGameStateAuthoritativeScore } from './world/WorldGameStateAuthoritativeScore.test.mjs';
 import { run as runProductionReadiness } from './production/ProductionReadiness.test.mjs';
 import { run as runEnginePublicBarrelImports } from './production/EnginePublicBarrelImports.test.mjs';
+import { run as runTestsValidationCombinedPass } from './production/TestsValidationCombinedPass.test.mjs';
 import { run as runStorageService } from './persistence/StorageService.test.mjs';
 import { run as runAssetValidationEngine } from './tools/AssetValidationEngine.test.mjs';
 import { run as runAssetUsageIntegration } from './tools/AssetUsageIntegration.test.mjs';
@@ -266,6 +267,7 @@ const tests = [
     ['ProjectileLabScene', runProjectileLabScene],
     ['EnginePublicBarrelImports', runEnginePublicBarrelImports],
     ['ProductionReadiness', runProductionReadiness],
+    ['TestsValidationCombinedPass', runTestsValidationCombinedPass],
     ['AttractModeController', runAttractModeController],
     ['SceneManager', runSceneManager],
     ['TransitionScene', runTransitionScene],

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-BUILD_PR_LEVEL_12_2D_CAPABILITY_TRACK_RESIDUE_ONLY`
	`1`	`+BUILD_PR_LEVEL_14_TESTS_VALIDATION_COMBINED_PASS`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-NEXT_LANE_SELECTION`
	`1`	`+BUILD_PR_LEVEL_14_TESTS_VALIDATION_RESIDUE_ONLY`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Residue-only closeout for 2D capability track`
	`1`	`+Combined tests/validation normalization pass`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Only remaining items touched; lane complete or blockers listed`
	`1`	`+tests normalized, coverage aligned, fixtures organized`