reusable bundle: a standard execution template, a Node.js rename engine snippet, and a path-mapping validator, all with the Windows-safe ZIP and fail-fast rules baked in

Author: DavidQ

docs/dev/codex_execution_template.md

@@ -0,0 +1,64 @@
+# Standard Codex Execution Template
+
+Use this block in every BUILD PR `docs/dev/codex_commands.md`.
+
+```md
+MODEL: GPT-5.4-codex
+REASONING: high
+
+COMMAND:
+Execute <BUILD_PR_NAME> exactly as written.
+
+EXECUTION ENVIRONMENT (MANDATORY):
+- Target platform: Windows
+- Prefer Node.js for path, rename, move, and ZIP-related work
+- Python is allowed if Node.js is not the best fit
+- DO NOT use PowerShell for:
+  - path construction
+  - directory renaming
+  - bulk file moves
+  - ZIP path generation
+
+POWERSHELL PROHIBITION (CRITICAL):
+The following patterns are NOT allowed:
+- "$var/path"
+- "${var}/path"
+- "$base\$child"
+- "$($var)/path"
+
+If any of these appear:
+- STOP
+- report the violation
+- do not silently retry
+
+EXECUTION RULES:
+- Read only the BUILD doc, exact target files, and immediate dependencies
+- Keep the changed-file count minimal
+- Do not broaden scope
+- Do not refactor outside the BUILD purpose
+- Preserve behavior unless the BUILD explicitly changes behavior
+- Do not modify `docs/dev/start_of_day/chatGPT/`
+- Do not modify `docs/dev/start_of_day/codex/`
+
+ZIP OUTPUT REQUIREMENT (HARD RULE):
+- MUST produce ZIP:
+  <project folder>/tmp/<BUILD_PR_NAME>.zip
+- ZIP must contain only repo-relevant output for this PR
+- Do not stage ZIP files from `<project folder>/tmp/`
+- Task is NOT complete until the ZIP exists at the exact requested path
+
+VALIDATION REQUIREMENT:
+- Run only the validation explicitly required by the BUILD
+- Report exact files changed
+- Report exact validation performed
+- Report ZIP output path
+
+FAIL FAST:
+- vague BUILD doc
+- conflicting target files
+- duplicate rename targets
+- numbering ambiguity
+- stale hardcoded links with no exact target list
+- any PowerShell parse issue before execution
+- missing ZIP output at exact path
+```

docs/dev/reports/execution_notes_windows_safe.txt

@@ -0,0 +1,18 @@
+WINDOWS-SAFE EXECUTION NOTES
+
+Standard recommendation:
+1. Run validator first:
+   node tools/codex/path_mapping_validator.js tools/codex/sample_mapping.example.json
+
+2. Run rename engine:
+   node tools/codex/node_rename_engine_template.js tools/codex/sample_mapping.example.json
+
+3. Validate required repo links and sample entry points.
+
+4. Package the PR ZIP to:
+   <project folder>/tmp/<BUILD_PR_NAME>.zip
+
+Hard rules:
+- No PowerShell interpolation for path work
+- No silent retries after parse errors
+- Missing ZIP at exact path = task failure

tools/codex/node_rename_engine_template.js

@@ -0,0 +1,111 @@
+/**
+ * Windows-safe rename/move engine template for Codex BUILD work.
+ * Uses Node.js path APIs only. No shell interpolation.
+ *
+ * Usage:
+ *   node tools/codex/node_rename_engine_template.js mapping.json
+ *
+ * mapping.json format:
+ * {
+ *   "projectRoot": "C:/Users/you/Documents/GitHub/HTML-JavaScript-Gaming",
+ *   "moves": [
+ *     { "from": "samples/Phase 13 - Network Concepts, Latency & Simulation (1301-1315)/1316_network_sample_a", "to": "samples/phase13/1316" }
+ *   ]
+ * }
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function exists(p) {
+  return fs.existsSync(p);
+}
+
+function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+function normalizeRel(relPath) {
+  return relPath.replace(/[\\/]+/g, "/").replace(/^\/+|\/+$/g, "");
+}
+
+function validateMapping(projectRoot, moves) {
+  assert(Array.isArray(moves) && moves.length > 0, "Mapping must contain at least one move.");
+  const targets = new Set();
+
+  for (const move of moves) {
+    assert(move.from && move.to, `Invalid move entry: ${JSON.stringify(move)}`);
+
+    const fromRel = normalizeRel(move.from);
+    const toRel = normalizeRel(move.to);
+
+    assert(/^samples\/phase\d{2}\/\d{4}$/.test(toRel.replace(/\//g, "/")) ||
+           /^samples\/phase\d{2}\/\d{4}$/.test(toRel.replace(/\//g, "/")) === false,
+           "Internal regex guard failure.");
+
+    assert(/^samples\/phase\d{2}\/\d{4}$/.test(toRel.replace(/\//g, "/")) ||
+           /^samples\/phase\d{2}\/\d{4}$/.test(toRel.replace(/\//g, "/")) === false,
+           "Internal regex guard failure.");
+  }
+
+  for (const move of moves) {
+    const fromRel = normalizeRel(move.from);
+    const toRel = normalizeRel(move.to);
+
+    assert(/^samples\/phase\d{2}\/\d{4}$/.test(toRel), `Target path must match samples/phasexx/xxyy: ${toRel}`);
+
+    const fromAbs = path.resolve(projectRoot, fromRel);
+    const toAbs = path.resolve(projectRoot, toRel);
+
+    assert(exists(fromAbs), `Source path missing: ${fromRel}`);
+    assert(!targets.has(toRel), `Duplicate target path: ${toRel}`);
+    targets.add(toRel);
+
+    if (exists(toAbs)) {
+      throw new Error(`Target already exists: ${toRel}`);
+    }
+  }
+}
+
+function movePath(projectRoot, fromRel, toRel) {
+  const fromAbs = path.resolve(projectRoot, normalizeRel(fromRel));
+  const toAbs = path.resolve(projectRoot, normalizeRel(toRel));
+  ensureDir(path.dirname(toAbs));
+  fs.renameSync(fromAbs, toAbs);
+  console.log(`MOVED: ${fromRel} -> ${toRel}`);
+}
+
+function main() {
+  const mappingFile = process.argv[2];
+  assert(mappingFile, "Usage: node tools/codex/node_rename_engine_template.js mapping.json");
+
+  const config = readJson(mappingFile);
+  const projectRoot = config.projectRoot;
+  const moves = config.moves;
+
+  assert(projectRoot, "mapping.json must include projectRoot");
+  validateMapping(projectRoot, moves);
+
+  for (const move of moves) {
+    movePath(projectRoot, move.from, move.to);
+  }
+
+  console.log("SUCCESS: All moves completed.");
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(`FAIL: ${err.message}`);
+  process.exit(1);
+}

tools/codex/path_mapping_validator.js

@@ -0,0 +1,66 @@
+/**
+ * Path mapping validator for sample normalization.
+ *
+ * Usage:
+ *   node tools/codex/path_mapping_validator.js mapping.json
+ *
+ * Checks:
+ * - target paths match samples/phasexx/xxyy
+ * - no duplicate targets
+ * - no spaces in normalized target paths
+ * - xxyy phase prefix matches phasexx
+ */
+
+const fs = require("fs");
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function normalizeRel(relPath) {
+  return relPath.replace(/[\\/]+/g, "/").replace(/^\/+|\/+$/g, "");
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function validateTarget(toRel) {
+  const normalized = normalizeRel(toRel);
+  assert(!/\s/.test(normalized), `Spaces are not allowed in target path: ${normalized}`);
+
+  const match = normalized.match(/^samples\/phase(\d{2})\/(\d{4})$/);
+  assert(match, `Target path must match samples/phasexx/xxyy: ${normalized}`);
+
+  const phase = match[1];
+  const sample = match[2];
+  assert(sample.startsWith(phase), `Sample number ${sample} does not belong under phase${phase}`);
+}
+
+function main() {
+  const mappingFile = process.argv[2];
+  assert(mappingFile, "Usage: node tools/codex/path_mapping_validator.js mapping.json");
+
+  const config = readJson(mappingFile);
+  assert(Array.isArray(config.moves), "mapping.json must include moves[]");
+
+  const targets = new Set();
+
+  for (const move of config.moves) {
+    assert(move.from && move.to, `Invalid move entry: ${JSON.stringify(move)}`);
+    validateTarget(move.to);
+
+    const normalizedTarget = normalizeRel(move.to);
+    assert(!targets.has(normalizedTarget), `Duplicate target path: ${normalizedTarget}`);
+    targets.add(normalizedTarget);
+  }
+
+  console.log("SUCCESS: mapping validation passed.");
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(`FAIL: ${err.message}`);
+  process.exit(1);
+}

tools/codex/sample_mapping.example.json

@@ -0,0 +1,17 @@
+{
+  "projectRoot": "C:/Users/davidq/Documents/GitHub/HTML-JavaScript-Gaming",
+  "moves": [
+    {
+      "from": "samples/Phase 13 - Network Concepts, Latency & Simulation (1301-1315)/1316_network_sample_a",
+      "to": "samples/phase13/1316"
+    },
+    {
+      "from": "samples/Phase 13 - Network Concepts, Latency & Simulation (1301-1315)/1317_network_sample_b",
+      "to": "samples/phase13/1317"
+    },
+    {
+      "from": "samples/Phase 13 - Network Concepts, Latency & Simulation (1301-1315)/1318_network_sample_c",
+      "to": "samples/phase13/1318"
+    }
+  ]
+}