Skip to content

Commit fc1e98b

Browse files
author
DavidQ
committed
BUILD_PR: metadata validation hardening and tag standardization
1 parent 5c32e01 commit fc1e98b

10 files changed

Lines changed: 211 additions & 136 deletions

docs/dev/CODEX_COMMANDS.md

Lines changed: 20 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,24 @@
1-
# Codex command for BUILD_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION
2-
31
MODEL: GPT-5.4-codex
42
REASONING: high
53

64
COMMAND:
7-
Execute BUILD_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION exactly as written.
8-
9-
EXECUTION ENVIRONMENT (MANDATORY):
10-
- Target platform: Windows
11-
- Prefer Node.js or vanilla JS for any scripting or generation support
12-
- DO NOT run `npm install`
13-
- DO NOT create `package.json`
14-
- DO NOT create `package-lock.json`
15-
- DO NOT create or populate `node_modules/`
16-
- DO NOT use PowerShell for path construction, rename-heavy work, or ZIP path generation
17-
18-
POWERSHELL PROHIBITION (CRITICAL):
19-
The following patterns are NOT allowed:
20-
- "$var/path"
21-
- "${var}/path"
22-
- "$base\$child"
23-
- "$($var)/path"
24-
25-
If any of these appear:
26-
- STOP
27-
- report the violation
28-
- do not silently retry
29-
30-
PR PURPOSE:
31-
Improve samples browse visuals and navigation in one narrow, testable wave.
32-
33-
EXPECTED TARGETS:
34-
- `samples/index.html`
35-
- minimal JS/CSS directly supporting thumbnails and hover preview
36-
- minimal sample detail page files directly supporting navigation polish
37-
- metadata-driven files directly needed for preview and navigation rendering
38-
- reporting docs under `docs/`
39-
40-
DO NOT:
41-
- modify gameplay code
42-
- modify engine core
43-
- change canonical paths
44-
- broaden scope beyond browse visuals and navigation
45-
- modify `docs/dev/start_of_day/chatGPT/`
46-
- modify `docs/dev/start_of_day/codex/`
47-
48-
REQUIRED IMPLEMENTATION SHAPE:
49-
1. Add thumbnail / preview asset support with clean fallback behavior
50-
2. Keep hover preview lightweight and dependency-free
51-
3. Polish next / previous / related navigation as needed
52-
4. Preserve canonical links and metadata-driven readable UI
53-
5. Keep changed-file count minimal
54-
55-
VALIDATION (REQUIRED):
56-
- load `samples/index.html`
57-
- verify thumbnails render when available
58-
- verify fallback behavior when previews are missing
59-
- verify hover preview does not break layout
60-
- open representative sample pages and validate navigation
61-
- confirm Phase 13 samples 1316, 1317, 1318 still load
62-
- confirm console is clean for tested pages
63-
- report exact files changed
64-
- report exact validation performed
65-
66-
ZIP OUTPUT REQUIREMENT (HARD RULE):
67-
- MUST produce ZIP:
68-
<project folder>/tmp/BUILD_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION.zip
69-
- ZIP must contain only repo-relevant delta output for this PR
70-
- Do not stage ZIP files from `<project folder>/tmp/`
71-
- Task is NOT complete until the ZIP exists at the exact requested path
72-
73-
FAIL FAST:
74-
- vague target files
75-
- broad asset reorganization required
76-
- preview conventions too inconsistent to implement narrowly
77-
- navigation changes require unrelated page rewrites
78-
- PowerShell parse issue before execution
79-
- missing ZIP output at exact path
5+
Execute BUILD_PR_SAMPLES_DISCOVERY_DATA_AND_FINDABILITY
6+
7+
ENVIRONMENT:
8+
- Windows
9+
- Node or vanilla JS only
10+
- NO npm
11+
- NO node_modules
12+
13+
RULES:
14+
- Do not change canonical paths
15+
- Do not modify gameplay or engine
16+
17+
VALIDATION:
18+
- metadata validation triggers on bad data
19+
- duplicate ids detected
20+
- tags normalized
21+
- filters/search still work
22+
23+
ZIP:
24+
<project folder>/tmp/BUILD_PR_SAMPLES_DISCOVERY_DATA_AND_FINDABILITY.zip

docs/dev/COMMIT_COMMENT.txt

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1 @@
1-
BUILD_PR: improve samples browse visuals and navigation
2-
3-
- add thumbnail / preview asset support with clean fallback behavior
4-
- add lightweight hover preview behavior
5-
- polish next/previous/related navigation surfaces
6-
- preserve canonical paths and metadata-driven readable UI
7-
8-
No gameplay or engine-core scope included
1+
BUILD_PR: metadata validation hardening and tag standardization
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
BUILD_PR_SAMPLES_DISCOVERY_DATA_AND_FINDABILITY
2+
3+
Scope confirmation:
4+
- No gameplay files changed
5+
- No engine-core files changed
6+
- Canonical sample paths preserved
7+
8+
Files changed for this BUILD:
9+
- scripts/generate-samples-index.mjs
10+
- samples/metadata/samples.index.metadata.json
11+
- samples/index.html
12+
- docs/dev/reports/BUILD_PR_SAMPLES_DISCOVERY_DATA_AND_FINDABILITY_validation.txt
13+
14+
Validation executed:
15+
1) node scripts/generate-samples-index.mjs --check
16+
- Result: OK phases=15 samples=197 metadata=197 mode=check
17+
18+
2) node scripts/generate-samples-index.mjs --self-test
19+
- Result: OK self-test metadata validation and tag normalization
20+
- Confirms:
21+
- invalid metadata is rejected
22+
- duplicate sample IDs are detected and rejected
23+
- tag normalization is deterministic
24+
25+
3) Normalized tags present in generated launcher links
26+
- Result: pass
27+
- Verified `data-tags` values for:
28+
- 1316 => network, phase-13, sample-a
29+
- 1317 => network, phase-13, sample-b
30+
- 1318 => network, phase-13, sample-c
31+
32+
4) Filter/search predictability checks against generated launcher links
33+
- Result: pass
34+
- Verified tag filter `network` includes 1316/1317/1318
35+
- Verified combined filter + search resolves `network sample b` to 1317
36+
37+
5) Console-clean guard check for tested UI files
38+
- Result: pass
39+
- No `console.log` / `console.warn` / `console.error` statements found in:
40+
- samples/index.html
41+
- samples/_shared/sampleDetailPageEnhancement.js
Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1 @@
1-
PR TYPE: BUILD
2-
PURPOSE: samples browse visuals and navigation
3-
4-
SUMMARY:
5-
- defines a testable BUILD wave for thumbnails, hover preview, and navigation polish
6-
- preserves canonical sample paths and metadata-driven readable UI
7-
- requires clean fallback behavior when preview assets are missing
8-
- keeps scope narrow and Windows-safe
1+
Add fail-fast metadata validation and normalize tags for consistent discovery
Lines changed: 4 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,6 @@
1-
EXPECTED DELTA (implementation-dependent, keep minimal)
2-
31
MODIFIED:
4-
- samples/index.html
5-
- minimal JS/CSS directly supporting browse visuals / hover behavior
6-
- minimal sample detail files directly supporting navigation polish
7-
8-
ADDED (only if required):
9-
- minimal preview asset mapping or helper file
10-
- minimal browse-visual support file directly used by the samples index
2+
- metadata layer
3+
- filter/search logic (minimal)
114

12-
REPORT ONLY:
13-
- docs/pr/BUILD_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION.md
14-
- docs/dev/codex_commands.md
15-
- docs/dev/commit_comment.txt
16-
- docs/dev/reports/change_summary.txt
17-
- docs/dev/reports/validation_checklist.txt
18-
- docs/dev/reports/file_tree_delta.txt
5+
ADDED:
6+
- validation logic (lightweight)
Lines changed: 7 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,7 @@
1-
[ ] samples/index.html renders thumbnails when available
2-
[ ] missing preview assets fall back cleanly
3-
[ ] hover preview works without breaking layout
4-
[ ] representative sample pages show correct navigation
5-
[ ] related links resolve correctly
6-
[ ] Phase 13 samples 1316, 1317, 1318 still load
7-
[ ] no console errors in tested pages
8-
[ ] no gameplay changes
9-
[ ] no engine-core changes
10-
[ ] changed-file count stayed minimal
11-
[ ] ZIP exists at <project folder>/tmp/BUILD_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION.zip
1+
[ ] metadata validation works
2+
[ ] duplicate ids fail
3+
[ ] duplicate entries fail
4+
[ ] tags normalized
5+
[ ] filters/search consistent
6+
[ ] no console errors
7+
[ ] zip exists
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# BUILD_PR_SAMPLES_DISCOVERY_DATA_AND_FINDABILITY
2+
3+
## Objective
4+
Improve discovery correctness by enforcing metadata validation and tag standardization.
5+
6+
## Scope
7+
- metadata validation (fail-fast)
8+
- duplicate detection (id, entry)
9+
- tag normalization (case, trimming)
10+
- ensure filter/search consistency
11+
12+
## Out of Scope
13+
- visuals (already handled)
14+
- navigation
15+
- performance tuning beyond correctness
16+
17+
## Acceptance
18+
- invalid metadata fails fast
19+
- duplicate ids rejected
20+
- duplicate entry paths rejected
21+
- tags normalized consistently
22+
- filters/search behave predictably

samples/index.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -370,9 +370,9 @@ <h2>Phase 13 - Network Concepts, Latency &amp;amp; Simulation (1301-1315)</h2>
370370
<a class="live" href="./phase13/1313/index.html" title="Pacman Lite World Systems" data-tags="">Sample 1313 - Pacman Lite World Systems</a>
371371
<a class="live" href="./phase13/1314/index.html" title="Chat Presence Layer" data-tags="">Sample 1314 - Chat Presence Layer</a>
372372
<a class="live" href="./phase13/1315/index.html" title="Rollback Replay Diagnostics" data-tags="">Sample 1315 - Rollback Replay Diagnostics</a>
373-
<a class="live" href="./phase13/1316/index.html" title="Network Sample A" data-tags="">Sample 1316 - Network Sample A</a>
374-
<a class="live" href="./phase13/1317/index.html" title="Network Sample B" data-tags="">Sample 1317 - Network Sample B</a>
375-
<a class="live" href="./phase13/1318/index.html" title="Network Sample C" data-tags="">Sample 1318 - Network Sample C</a>
373+
<a class="live" href="./phase13/1316/index.html" title="Network Sample A" data-tags="network, phase-13, sample-a">Sample 1316 - Network Sample A</a>
374+
<a class="live" href="./phase13/1317/index.html" title="Network Sample B" data-tags="network, phase-13, sample-b">Sample 1317 - Network Sample B</a>
375+
<a class="live" href="./phase13/1318/index.html" title="Network Sample C" data-tags="network, phase-13, sample-c">Sample 1318 - Network Sample C</a>
376376
</div>
377377
</section>
378378
<section>

samples/metadata/samples.index.metadata.json

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1273,7 +1273,11 @@
12731273
"phase": "13",
12741274
"title": "Network Sample A",
12751275
"description": "Network Sample A",
1276-
"tags": [],
1276+
"tags": [
1277+
"network",
1278+
"phase-13",
1279+
"sample-a"
1280+
],
12771281
"thumbnail": "/samples/phase13/1316/assets/preview.svg",
12781282
"preview": "/samples/phase13/1316/assets/preview.svg"
12791283
},
@@ -1282,7 +1286,11 @@
12821286
"phase": "13",
12831287
"title": "Network Sample B",
12841288
"description": "Network Sample B",
1285-
"tags": [],
1289+
"tags": [
1290+
"network",
1291+
"phase-13",
1292+
"sample-b"
1293+
],
12861294
"thumbnail": "/samples/phase13/1317/assets/preview.svg",
12871295
"preview": "/samples/phase13/1317/assets/preview.svg"
12881296
},
@@ -1291,7 +1299,11 @@
12911299
"phase": "13",
12921300
"title": "Network Sample C",
12931301
"description": "Network Sample C",
1294-
"tags": [],
1302+
"tags": [
1303+
"network",
1304+
"phase-13",
1305+
"sample-c"
1306+
],
12951307
"thumbnail": "/samples/phase13/1318/assets/preview.svg",
12961308
"preview": "/samples/phase13/1318/assets/preview.svg"
12971309
},

0 commit comments

Comments
 (0)