BUILD_PR: add metadata layer for samples and integrate with index generation

DavidQ · DavidQ · commit 1e8254e9d05c · 2026-04-10T16:08:11.000-04:00
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,43 +1,14 @@
-# Codex command for PLAN_PR_SAMPLES_METADATA_LAYER
-
 MODEL: GPT-5.4-codex
 REASONING: high
 
 COMMAND:
-Create PLAN_PR_SAMPLES_METADATA_LAYER as docs-only planning.
-
-OBJECTIVE:
-Define a minimal metadata layer for canonical sample paths so the generated samples index can render stable human-readable titles, descriptions, and tags.
-
-CONSTRAINTS:
-- docs only
-- no implementation code changes
-- no gameplay scope
-- no engine-core scope
-- no start_of_day directory changes
-
-PLANNING REQUIREMENTS:
-1. Define the minimal metadata schema
-2. Define where the metadata should live
-3. Define source-of-truth boundaries between:
-   - canonical folder structure
-   - metadata content
-   - generated index rendering
-4. Define fail-fast rules for:
-   - duplicate IDs
-   - duplicate entries
-   - phase/sample mismatches
-   - missing required fields
-5. Keep the future BUILD testable and narrowly scoped
+Execute BUILD_PR_SAMPLES_METADATA_LAYER
 
-OUTPUT FILES:
-- docs/pr/PLAN_PR_SAMPLES_METADATA_LAYER.md
-- docs/dev/commit_comment.txt
-- docs/dev/reports/change_summary.txt
-- docs/dev/reports/validation_checklist.txt
-- docs/dev/reports/file_tree_delta.txt
+ENVIRONMENT:
+- Windows
+- Use Node.js only
+- No npm install
+- No node_modules
 
-ZIP OUTPUT REQUIREMENT:
-- MUST produce ZIP:
-  <project folder>/tmp/PLAN_PR_SAMPLES_METADATA_LAYER.zip
-- Task is not complete until the ZIP exists at that exact path
+ZIP:
+<project folder>/tmp/BUILD_PR_SAMPLES_METADATA_LAYER.zip
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,7 +1 @@
-PLAN_PR_SAMPLES_METADATA_LAYER
-
-- Define minimal samples metadata schema for generated index rendering
-- Define metadata location and source-of-truth boundaries
-- Define fail-fast validation rules (duplicates, mismatches, missing fields)
-- Keep future BUILD narrowly scoped and testable
-- Docs-only planning; no implementation code changes
+BUILD_PR: add metadata layer for samples and integrate with index generation
diff --git a/docs/dev/reports/BUILD_PR_SAMPLES_METADATA_LAYER_validation.txt b/docs/dev/reports/BUILD_PR_SAMPLES_METADATA_LAYER_validation.txt
@@ -0,0 +1,34 @@
+BUILD_PR_SAMPLES_METADATA_LAYER VALIDATION REPORT
+
+Files changed for this BUILD:
+- scripts/generate-samples-index.mjs
+- samples/metadata/samples.index.metadata.json
+- samples/index.html
+- docs/dev/reports/BUILD_PR_SAMPLES_METADATA_LAYER_validation.txt
+
+Validation executed:
+1) node scripts/generate-samples-index.mjs
+   - OK phases=15 samples=197 metadata=197 mode=write
+2) node scripts/generate-samples-index.mjs --check
+   - OK phases=15 samples=197 metadata=197 mode=check
+3) Representative link checks from generated index:
+   - first sample in a populated phase: 0101 -> ./phase01/0101/index.html
+   - last sample in a populated phase: 1506 -> ./phase15/1506/index.html
+   - phase 13 samples: 1316, 1317, 1318 present and resolvable
+
+Fail-fast checks implemented in generator:
+- malformed phase folders
+- malformed sample folders
+- duplicate sample IDs in canonical tree
+- missing canonical sample entrypoint index.html
+- missing metadata file
+- duplicate metadata phase entries
+- duplicate metadata sample entries
+- phase/sample mismatches
+- missing required metadata fields
+- non-canonical metadata phase/sample entries
+
+Scope confirmation:
+- gameplay untouched
+- engine core untouched
+- implementation limited to samples metadata layer + index generation integration
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,11 +1 @@
-CHANGE SUMMARY
-
-Purpose:
-- prevent accidental dependency installation in repo workflow
-- prohibit node_modules creation
-- add cleanup scripts for repo-root node_modules deletion
-
-Included:
-- Codex rule updates
-- workflow/checklist/stop-condition updates
-- delete scripts: PowerShell, batch, and zero-dependency Node.js
+Add metadata layer, integrate with index, validate canonical paths
diff --git a/docs/dev/reports/file_tree_delta.txt b/docs/dev/reports/file_tree_delta.txt
@@ -1,12 +1,5 @@
-PLAN_PR_SAMPLES_METADATA_LAYER DELTA
+ADDED:
+- metadata source file
 
-Modified:
-- docs/pr/PLAN_PR_SAMPLES_METADATA_LAYER.md
-- docs/dev/commit_comment.txt
-- docs/dev/reports/change_summary.txt
-- docs/dev/reports/validation_checklist.txt
-- docs/dev/reports/file_tree_delta.txt
-
-Scope:
-- docs-only planning
-- no implementation/runtime code changes
+MODIFIED:
+- samples/index.html
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,6 +1,5 @@
-[ ] Codex docs explicitly prohibit npm install / npm init
-[ ] Codex docs explicitly prohibit package.json / package-lock.json creation without approval
-[ ] Codex docs explicitly prohibit repo-root node_modules
-[ ] node_modules appearance is defined as stop-and-report
-[ ] cleanup scripts target only repo-root node_modules
-[ ] bundle ZIP exists under <project folder>/tmp/
+[ ] metadata file exists
+[ ] ids match folders
+[ ] index renders titles
+[ ] no broken links
+[ ] zip exists
diff --git a/docs/pr/BUILD_PR_SAMPLES_METADATA_LAYER.md b/docs/pr/BUILD_PR_SAMPLES_METADATA_LAYER.md
@@ -0,0 +1,18 @@
+# BUILD_PR_SAMPLES_METADATA_LAYER
+
+## Objective
+Implement metadata layer for samples and integrate with index generation.
+
+## Scope
+- Add metadata source (JSON or JS)
+- Wire into samples index generation
+- Validate against canonical paths (phasexx/xxyy)
+
+## Out of Scope
+- gameplay
+- engine changes
+
+## Acceptance
+- metadata drives titles/descriptions
+- links resolve correctly
+- fail-fast on mismatches
diff --git a/samples/index.html b/samples/index.html
diff --git a/samples/metadata/samples.index.metadata.json b/samples/metadata/samples.index.metadata.json
diff --git a/scripts/generate-samples-index.mjs b/scripts/generate-samples-index.mjs
