PLAN_PR: Define normalized sample directory contract

- Standardize samples to `samples/phasexx/xxyy/index.html`
- Remove spaces and descriptive text from sample directories
- Preserve phase/sample labels in headers and index tiles
- Keep scope limited to samples structure and wiring only
&
BUILD_PR: normalize sample directories to phasexx/xxyy structure

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,36 +1,11 @@
-MODEL: GPT-5.4
+MODEL: GPT-5.4-codex
 REASONING: high
 
 COMMAND:
+Execute BUILD_PR_SAMPLES_DIRECTORY_NORMALIZATION
 
-Create APPLY_PR_NETWORK_SAMPLES_RELOCATION_FROM_GAMES_TO_SAMPLES
+OUTPUT REQUIREMENT:
+- Produce ZIP at:
+<project folder>/tmp/BUILD_PR_SAMPLES_DIRECTORY_NORMALIZATION.zip
 
-Apply the approved relocation exactly as documented in BUILD_PR_NETWORK_SAMPLES_RELOCATION_FROM_GAMES_TO_SAMPLES (v3).
-
-Execution rules:
-- Move only:
-  - games/network_sample_a
-  - games/network_sample_b
-  - games/network_sample_c
-- Destination only:
-  - samples/Phase 13 - Network Concepts, Latency & Simulation (1301-1315)/1316_network_sample_a
-  - samples/Phase 13 - Network Concepts, Latency & Simulation (1301-1315)/1317_network_sample_b
-  - samples/Phase 13 - Network Concepts, Latency & Simulation (1301-1315)/1318_network_sample_c
-- Remove corresponding entries from games/index.html
-- Add corresponding entries to samples/index.html
-- Preserve behavior and folder contents
-- Do not change gameplay, engine code, assets, or unrelated indexes
-
-Validation:
-- Confirm samples launch from new locations
-- Confirm no duplicate index exposure
-- Confirm no broken relative paths
-- Confirm tests remain green
-- Package only the required apply-ready delta
-
-Output:
-- Commit-ready apply bundle
-- Keep docs under docs/pr and docs/dev
-- Keep reports under docs/dev/reports
-- Target zip path:
-  HTML-JavaScript-Gaming/tmp/APPLY_PR_NETWORK_SAMPLES_RELOCATION_FROM_GAMES_TO_SAMPLES.zip
+FAIL IF ZIP NOT PRODUCED

docs/dev/COMMIT_COMMENT.txt

@@ -1,11 +1 @@
-APPLY_PR: network samples Phase 13 destination normalization to underscore paths
-
-- Normalized Phase 13 sample folders:
-  1316-network-sample-a -> 1316_network_sample_a
-  1317-network-sample-b -> 1317_network_sample_b
-  1318-network-sample-c -> 1318_network_sample_c
-- Updated samples/index.html links for 1316/1317/1318
-- Fixed one cross-sample import path in 1317_network_sample_b to the renamed 1316 path
-- Kept games/index.html unchanged (network entries were already removed)
-- Updated shared extraction guard baseline path entries to keep pretest green
-- No gameplay/engine logic changes
+BUILD_PR: normalize sample directories to phasexx/xxyy structure

docs/dev/reports/change_summary.txt

@@ -1,20 +1,2 @@
-TYPE: APPLY / STRUCTURAL
-
-Applied relocation finalization for Network Sample A/B/C in Phase 13 with required underscore destinations.
-
-Changed:
-- Renamed folder: 1316-network-sample-a -> 1316_network_sample_a
-- Renamed folder: 1317-network-sample-b -> 1317_network_sample_b
-- Renamed folder: 1318-network-sample-c -> 1318_network_sample_c
-- Updated links in samples/index.html for 1316/1317/1318
-- Fixed one cross-sample import path to the renamed 1316 destination
-- Updated shared extraction guard baseline paths for renamed folders
-
-Verified no additional canonical cleanup was needed:
-- games/index.html already had network sample entries removed
-
-Not changed:
-- Gameplay logic
-- Engine/shared runtime logic
-- Asset contents
-- Unrelated indexes
+TYPE: STRUCTURE ONLY
+Normalize samples directories and paths

docs/dev/reports/file_tree_delta.txt

@@ -1,14 +1 @@
-APPLY DELTA
-
-RENAMED (Phase 13 destination normalization):
-- samples/Phase 13 - Network Concepts, Latency & Simulation (1301-1315)/1316-network-sample-a
-  -> samples/Phase 13 - Network Concepts, Latency & Simulation (1301-1315)/1316_network_sample_a
-- samples/Phase 13 - Network Concepts, Latency & Simulation (1301-1315)/1317-network-sample-b
-  -> samples/Phase 13 - Network Concepts, Latency & Simulation (1301-1315)/1317_network_sample_b
-- samples/Phase 13 - Network Concepts, Latency & Simulation (1301-1315)/1318-network-sample-c
-  -> samples/Phase 13 - Network Concepts, Latency & Simulation (1301-1315)/1318_network_sample_c
-
-MODIFIED:
-- samples/index.html
-- samples/Phase 13 - Network Concepts, Latency & Simulation (1301-1315)/1317_network_sample_b/game/FakeHostClientNetworkModel.js
-- tools/dev/checkSharedExtractionGuard.baseline.json
+All samples directories will be renamed to phasexx/xxyy

docs/dev/reports/samples_directory_normalization_mapping_expectations.txt

@@ -0,0 +1,40 @@
+SAMPLES DIRECTORY NORMALIZATION - MAPPING/REPORT EXPECTATIONS
+
+Contract:
+- samples/phasexx/xxyy/index.html
+- xx = phase number
+- yy = sample number
+
+Mapping table requirements (mandatory columns):
+1) old_path
+2) new_path
+3) phase_xx
+4) sample_xxyy
+5) index_tile_updated (yes/no)
+6) sample_header_preserved (yes/no)
+7) relative_paths_validated (yes/no)
+8) behavior_check (pass/fail)
+9) notes
+
+Report outputs expected from BUILD/APPLY:
+- docs/dev/reports/change_summary.txt
+- docs/dev/reports/file_tree_delta.txt
+- docs/dev/reports/validation_checklist.txt
+- optional: docs/dev/reports/samples_directory_normalization_mapping.csv
+
+Reporting rules:
+- Report only normalization-related files.
+- Distinguish renamed paths from edited files.
+- Include explicit old->new mapping lines.
+- Record unresolved or deferred items separately.
+- Do not include unrelated repo edits.
+
+Index/report expectations:
+- samples/index links must target normalized paths.
+- Any previous non-normalized path exposure must be listed and removed in report.
+- Human-readable titles must be preserved in UI text and called out as validated.
+
+Completion signal:
+- Mapping table complete for all samples.
+- Validation checklist all green.
+- Scope clean (samples normalization only).

docs/dev/reports/validation_checklist.txt

@@ -1,16 +1,4 @@
-[x] network_sample_a launches from Phase 13 / 1316 (folder + entrypoint present)
-[x] network_sample_b launches from Phase 13 / 1317 (folder + entrypoint present)
-[x] network_sample_c launches from Phase 13 / 1318 (folder + entrypoint present)
-[x] games/index.html no longer lists network_sample_a
-[x] games/index.html no longer lists network_sample_b
-[x] games/index.html no longer lists network_sample_c
-[x] samples/index.html lists 1316, 1317, 1318 correctly
-[x] No duplicate entries across indexes
-[x] Relative asset/script paths resolve
-[!] Existing tests remain green (blocked by runtime environment)
-
-Notes:
-- pretest (`node tools/dev/checkSharedExtractionGuard.mjs`) passes after baseline update.
-- full `npm test` fails in this environment on Node v20.8.1 because
-  `scripts/run-node-tests.mjs` imports `registerHooks` from `node:module`,
-  which is unavailable in this Node version.
+[ ] All samples map to /samples/phasexx/xxyy/index.html
+[ ] No spaces in directories
+[ ] Links updated
+[ ] No broken paths

docs/pr/BUILD_PR_SAMPLES_DIRECTORY_NORMALIZATION.md

@@ -0,0 +1,13 @@
+# BUILD_PR_SAMPLES_DIRECTORY_NORMALIZATION
+
+Objective:
+Normalize samples directory to canonical structure:
+samples/phasexx/xxyy/index.html
+
+Scope:
+- Rename phase folders → phasexx
+- Rename sample folders → xxyy
+- Update index wiring
+- Preserve behavior
+
+No gameplay or engine changes.

docs/pr/PLAN_PR_SAMPLES_DIRECTORY_NORMALIZATION.md

@@ -0,0 +1,78 @@
+# PLAN_PR: Samples Directory Normalization
+
+## Purpose
+Define a docs-only, repo-wide normalization plan for sample paths using this exact contract:
+
+`samples/phasexx/xxyy/index.html`
+
+Where:
+- `xx` = phase number
+- `yy` = sample number
+
+## Scope
+Planning docs only.
+No implementation code, no folder moves, no path rewrites, no runtime edits.
+
+## Required Contract
+- All sample entrypoints must normalize to `samples/phasexx/xxyy/index.html`.
+- Remove spaces from directory names.
+- Remove descriptive text from directory names.
+- Preserve human-readable phase/sample text in index tiles and sample headers.
+- Preserve behavior.
+
+## Directory Rules
+- Phase folder format: `phasexx`
+- Sample folder format: `xxyy`
+- No phase titles or descriptive labels in directory names.
+- Human-readable names remain in UI text only.
+
+## Deliverables in This Planning PR
+1. PR plan (this file)
+2. Mapping/report expectations
+3. Validation checklist
+4. Commit comment
+
+## Future BUILD Strategy (No Execution Here)
+1. Inventory all current sample entrypoints.
+2. Generate one mapping table: old path -> normalized path.
+3. Update `samples/index.html` links to normalized paths while preserving tile text.
+4. Update sample headers so titles remain human-readable and independent of folder names.
+5. Validate all normalized entrypoints and relative references.
+6. Remove obsolete path exposure only after successful path validation.
+
+## Mapping Requirements for BUILD
+Each mapped row must include:
+- old directory path
+- new normalized path (`samples/phasexx/xxyy/`)
+- phase number (`xx`)
+- sample id (`xxyy`)
+- index tile reference status
+- header text preservation status
+- validation status (pass/fail)
+
+## Validation Requirements for BUILD
+- Every sample launches from normalized path.
+- No duplicate exposure between old and new links.
+- No broken relative imports/assets from renamed paths.
+- Human-readable phase/sample text remains visible in index tiles and sample headers.
+- Behavior parity preserved.
+
+## Out of Scope
+- Gameplay changes
+- Engine/shared refactors
+- Tooling refactors unrelated to path normalization
+- Any non-samples directory restructuring
+
+## Fail-Fast Conditions
+Stop the BUILD if any of the following occur:
+- ambiguous phase/sample id mapping
+- conflicting entrypoint ownership for the same `xxyy`
+- unresolved relative-path breakage with no safe deterministic fix
+- scope expansion beyond sample path normalization
+
+## Acceptance Criteria for This PLAN
+- Contract is explicit and unambiguous.
+- Mapping/report expectations are documented.
+- Validation checklist is documented.
+- Commit comment is prepared.
+- No implementation code changes were made.