Skip to content

Commit 2779622

Browse files
author
DavidQ
committed
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
1 parent 8af9355 commit 2779622

6 files changed

Lines changed: 164 additions & 113 deletions

File tree

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 37 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,83 +1,43 @@
1-
# Codex command for BUILD_PR_SAMPLES_INDEX_AUTOGENERATION
1+
# Codex command for PLAN_PR_SAMPLES_METADATA_LAYER
22

33
MODEL: GPT-5.4-codex
44
REASONING: high
55

66
COMMAND:
7-
Execute BUILD_PR_SAMPLES_INDEX_AUTOGENERATION exactly as written.
8-
9-
EXECUTION ENVIRONMENT (MANDATORY):
10-
- Target platform: Windows
11-
- Prefer Node.js for path discovery, generation, and validation
12-
- Python is allowed if Node.js is not the best fit
13-
- DO NOT use PowerShell for:
14-
- path construction
15-
- directory scanning
16-
- bulk file moves
17-
- ZIP path generation
18-
19-
POWERSHELL PROHIBITION (CRITICAL):
20-
The following patterns are NOT allowed:
21-
- "$var/path"
22-
- "${var}/path"
23-
- "$base\$child"
24-
- "$($var)/path"
25-
26-
If any of these appear:
27-
- STOP
28-
- report the violation
29-
- do not silently retry
30-
31-
PR PURPOSE:
32-
Auto-generate the samples index from canonical sample folders in a testable way.
33-
34-
EXPECTED TARGETS:
35-
- `samples/index.html`
36-
- exact generator/helper files required for sample index generation
37-
- minimal supporting config/data files only if required
38-
- reporting docs under `docs/`
39-
40-
DO NOT:
41-
- modify gameplay code
42-
- modify engine core
43-
- perform unrelated cleanup
44-
- broaden scope beyond sample index generation
45-
- modify `docs/dev/start_of_day/chatGPT/`
46-
- modify `docs/dev/start_of_day/codex/`
47-
48-
REQUIRED IMPLEMENTATION SHAPE:
49-
1. Discover canonical sample folders under `samples/phaseXX/XXYY/`
50-
2. Build or update the minimal generation path needed for `samples/index.html`
51-
3. Preserve human-readable labels in UI
52-
4. Fail fast on:
53-
- malformed sample paths
54-
- duplicate sample numbers
55-
- missing sample entry points
56-
- ambiguous phase/sample metadata
57-
5. Keep changed-file count minimal
58-
59-
VALIDATION (REQUIRED):
60-
- load `samples/index.html`
61-
- verify generated tiles render
62-
- open representative sample links:
63-
- first sample in a populated phase
64-
- last sample in a populated phase
65-
- Phase 13 samples 1316, 1317, 1318
66-
- confirm console is clean for tested pages
67-
- report exact files changed
68-
- report exact validation performed
69-
70-
ZIP OUTPUT REQUIREMENT (HARD RULE):
7+
Create PLAN_PR_SAMPLES_METADATA_LAYER as docs-only planning.
8+
9+
OBJECTIVE:
10+
Define a minimal metadata layer for canonical sample paths so the generated samples index can render stable human-readable titles, descriptions, and tags.
11+
12+
CONSTRAINTS:
13+
- docs only
14+
- no implementation code changes
15+
- no gameplay scope
16+
- no engine-core scope
17+
- no start_of_day directory changes
18+
19+
PLANNING REQUIREMENTS:
20+
1. Define the minimal metadata schema
21+
2. Define where the metadata should live
22+
3. Define source-of-truth boundaries between:
23+
- canonical folder structure
24+
- metadata content
25+
- generated index rendering
26+
4. Define fail-fast rules for:
27+
- duplicate IDs
28+
- duplicate entries
29+
- phase/sample mismatches
30+
- missing required fields
31+
5. Keep the future BUILD testable and narrowly scoped
32+
33+
OUTPUT FILES:
34+
- docs/pr/PLAN_PR_SAMPLES_METADATA_LAYER.md
35+
- docs/dev/commit_comment.txt
36+
- docs/dev/reports/change_summary.txt
37+
- docs/dev/reports/validation_checklist.txt
38+
- docs/dev/reports/file_tree_delta.txt
39+
40+
ZIP OUTPUT REQUIREMENT:
7141
- MUST produce ZIP:
72-
<project folder>/tmp/BUILD_PR_SAMPLES_INDEX_AUTOGENERATION.zip
73-
- ZIP must contain only repo-relevant delta output for this PR
74-
- Do not stage ZIP files from `<project folder>/tmp/`
75-
- Task is NOT complete until the ZIP exists at the exact requested path
76-
77-
FAIL FAST:
78-
- vague BUILD doc
79-
- conflicting target files
80-
- generator path would require broad repo analysis
81-
- malformed canonical sample directories
82-
- PowerShell parse issue before execution
83-
- missing ZIP output at exact path
42+
<project folder>/tmp/PLAN_PR_SAMPLES_METADATA_LAYER.zip
43+
- Task is not complete until the ZIP exists at that exact path

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
1-
BUILD_PR: auto-generate samples index from canonical sample folders
1+
PLAN_PR_SAMPLES_METADATA_LAYER
22

3-
- define minimal, testable BUILD for generated samples index
4-
- preserve readable UI labels while using canonical paths
5-
- require representative runtime validation
6-
- enforce Windows-safe execution and exact ZIP output path
7-
8-
No gameplay or engine-core scope included
3+
- Define minimal samples metadata schema for generated index rendering
4+
- Define metadata location and source-of-truth boundaries
5+
- Define fail-fast validation rules (duplicates, mismatches, missing fields)
6+
- Keep future BUILD narrowly scoped and testable
7+
- Docs-only planning; no implementation code changes

‎docs/dev/reports/change_summary.txt‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
1-
PR TYPE: BUILD
2-
PURPOSE: testable samples index autogeneration
1+
TYPE: PLANNING ONLY
32

4-
SUMMARY:
5-
- introduces a docs-first BUILD bundle for replacing manual samples index maintenance
6-
- requires generation from canonical `samples/phaseXX/XXYY/` structure
7-
- requires runtime-visible validation of generated tiles and links
8-
- preserves readable labels in UI
9-
- keeps scope narrow and Windows-safe
3+
Created planning artifacts for a minimal samples metadata layer.
4+
5+
Included in plan:
6+
- minimal metadata schema (`id`, `phase`, `title`, `description`, `tags`)
7+
- metadata location proposal (`samples/metadata/samples.index.metadata.json`)
8+
- source-of-truth boundaries between canonical folders, metadata, and generated index
9+
- fail-fast rules for duplicates, mismatches, and missing required fields
10+
- narrow, testable BUILD shape for future implementation
11+
12+
No gameplay, engine-core, or implementation code changes.

‎docs/dev/reports/file_tree_delta.txt‎

Lines changed: 7 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,12 @@
1-
EXPECTED DELTA (implementation-dependent, keep minimal)
1+
PLAN_PR_SAMPLES_METADATA_LAYER DELTA
22

3-
MODIFIED:
4-
- samples/index.html
5-
- minimal generator/helper files directly used by sample index generation
6-
7-
ADDED (only if required):
8-
- minimal generation utility or data file supporting samples index generation
9-
10-
REPORT ONLY:
11-
- docs/pr/BUILD_PR_SAMPLES_INDEX_AUTOGENERATION.md
12-
- docs/dev/codex_commands.md
3+
Modified:
4+
- docs/pr/PLAN_PR_SAMPLES_METADATA_LAYER.md
135
- docs/dev/commit_comment.txt
146
- docs/dev/reports/change_summary.txt
157
- docs/dev/reports/validation_checklist.txt
168
- docs/dev/reports/file_tree_delta.txt
9+
10+
Scope:
11+
- docs-only planning
12+
- no implementation/runtime code changes

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
[ ] samples/index.html uses generated or generation-backed sample tile data
2-
[ ] generated tiles render correctly
3-
[ ] first sample in a populated phase opens successfully
4-
[ ] last sample in a populated phase opens successfully
5-
[ ] Phase 13 samples 1316, 1317, 1318 open successfully
6-
[ ] console clean for tested pages
7-
[ ] no gameplay changes
8-
[ ] no engine-core changes
9-
[ ] changed-file count stayed minimal
10-
[ ] ZIP exists at <project folder>/tmp/BUILD_PR_SAMPLES_INDEX_AUTOGENERATION.zip
1+
[x] Docs-only scope preserved
2+
[x] No gameplay scope introduced
3+
[x] No engine-core scope introduced
4+
[x] No start_of_day directory changes
5+
[x] Minimal metadata schema defined
6+
[x] Metadata location defined
7+
[x] Source-of-truth boundaries defined
8+
[x] Fail-fast rules defined (duplicates, mismatches, missing fields)
9+
[x] Future BUILD testability gates documented
10+
[x] Future BUILD kept narrowly scoped

‎docs/pr/PLAN_PR_SAMPLES_METADATA_LAYER.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# PLAN_PR_SAMPLES_METADATA_LAYER
2+
3+
## Objective
4+
Define a minimal metadata layer for canonical sample paths so generated `samples/index.html` rendering has stable, human-readable titles, descriptions, and tags.
5+
6+
## Scope
7+
Docs-only planning.
8+
No implementation code changes.
9+
No gameplay scope.
10+
No engine-core scope.
11+
No start_of_day directory changes.
12+
13+
## Canonical Path Contract (Source of Truth #1)
14+
- Folder structure remains canonical: `samples/phaseXX/XXYY/index.html`
15+
- Path shape determines discoverability and link targets.
16+
- Path shape does not own display copy.
17+
18+
## Minimal Metadata Schema (Source of Truth #2)
19+
Proposed schema for each sample entry:
20+
- `id` (string, required): 4-digit sample id, e.g. `1316`
21+
- `phase` (string, required): 2-digit phase id, e.g. `13`
22+
- `title` (string, required): stable human-readable sample title
23+
- `description` (string, required): short tile/section description
24+
- `tags` (array<string>, required, may be empty): filter/display tags
25+
26+
Derived (not stored) fields:
27+
- `href`: computed from canonical folders -> `./phaseXX/XXYY/index.html`
28+
29+
## Metadata Location
30+
Single metadata file, repo-local and minimal:
31+
- `samples/metadata/samples.index.metadata.json`
32+
33+
Why this location:
34+
- keeps sample-display content near samples domain
35+
- avoids engine/tool coupling
36+
- provides one narrow source for index-render copy
37+
38+
## Source-of-Truth Boundaries
39+
1. Canonical folder structure (`samples/phaseXX/XXYY/`):
40+
- owns existence/discovery of runnable sample entrypoints
41+
- owns path validity
42+
43+
2. Metadata file (`samples.index.metadata.json`):
44+
- owns titles/descriptions/tags
45+
- must not define non-canonical paths
46+
47+
3. Generated index rendering (`samples/index.html`):
48+
- owns final HTML presentation only
49+
- consumes canonical discovery + metadata
50+
- must not become a manual content source
51+
52+
## Fail-Fast Rules for Future BUILD
53+
Stop generation immediately when any of the following occur:
54+
- duplicate IDs in metadata
55+
- duplicate metadata entries for same sample id
56+
- phase/sample mismatch:
57+
- metadata `phase` does not match `id[:2]`
58+
- metadata id not found in canonical folder structure
59+
- canonical sample missing corresponding metadata entry (if strict mode enabled)
60+
- missing required fields (`id`, `phase`, `title`, `description`, `tags`)
61+
- non-array `tags`
62+
- malformed canonical directories (`phaseXX` / `XXYY` violations)
63+
- missing canonical sample entrypoint `index.html`
64+
65+
## Future BUILD Shape (Narrow + Testable)
66+
1. Discover canonical samples from `samples/phaseXX/XXYY/`.
67+
2. Load and validate metadata file with fail-fast checks.
68+
3. Join canonical set + metadata by sample id.
69+
4. Generate index sections/tiles from joined data.
70+
5. Validate representative links and console cleanliness.
71+
72+
## Testability Requirements for Future BUILD
73+
Minimum testability gates:
74+
- `samples/index.html` loads after generation
75+
- representative links open correctly:
76+
- first sample in first populated phase
77+
- last sample in last populated phase
78+
- phase 13 samples: 1316, 1317, 1318
79+
- no console errors for tested pages
80+
- generated output remains deterministic for unchanged inputs
81+
82+
## Out of Scope
83+
- changing gameplay code
84+
- changing engine core
85+
- broad refactors
86+
- modifying start_of_day instruction directories
87+
88+
## Acceptance Criteria (Planning PR)
89+
- minimal schema defined
90+
- metadata location defined
91+
- source-of-truth boundaries defined
92+
- fail-fast rules defined
93+
- future BUILD remains narrowly scoped and testable

0 commit comments

Comments
 (0)