Toolbox Aid

David Quesenberry
04/05/2026
commit_comment.txt

docs: harden unified 2D render pipeline contract, validation, composition, and engine mappings for all four tools

Author: DavidQ

HTML-JavaScript-Gaming-main/tmp/BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS_delta.zip

@@ -10,26 +10,44 @@ codex_commands.md
 - Reasoning: high
 
 ## Primary Command
-Create BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS as a docs-only, repo-structured delta.
+Create BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS as a docs-only, repo-structured delta that fixes all remaining contract gaps in one PR.
 
 Requirements:
-- Follow PLAN_PR -> BUILD_PR -> APPLY_PR
+- Follow PLAN_PR -> BUILD_PR -> APPLY_PR exactly
 - Docs-first only
 - No implementation code in the bundle
-- One PR per purpose
+- One PR purpose only
 - Preserve exact repo-relative structure inside the ZIP
 - Place outputs under docs/pr and docs/dev
 - Use docs/dev/codex_commands.md and docs/dev/commit_comment.txt
+- Include docs/dev/next_command.txt
+- Respect the repo file-header standard on every created file
+- Tighten contract schemas for all 4 tools
+- Define the render pipeline formally
+- Lock engine mappings explicitly
+- Add a validation layer with non-silent rejection rules
+- Add a composition layer with a formal composition document schema
+- Keep all scope 2D-only and non-destructive
 - Output ZIP path:
   - HTML-JavaScript-Gaming-main/tmp/BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS_delta.zip
 
-Deliverables:
+Required deliverables:
 - docs/pr/BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS.md
 - docs/dev/codex_commands.md
 - docs/dev/commit_comment.txt
 - docs/dev/change_summary.txt
 - docs/dev/validation_checklist.txt
 - docs/dev/file_tree.txt
+- docs/dev/next_command.txt
+
+Hard acceptance targets:
+- All four producers have explicit schema sections
+- Formal pipeline stages are documented
+- Formal render order buckets are documented
+- Engine mappings are explicit and locked
+- Validation rules reject invalid contracts without silent repair
+- Composition manifest schema is documented
+- No implementation files are added
 
 Next command:
 - APPLY_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS

docs/dev/CODEX_COMMANDS.md

@@ -3,4 +3,4 @@ David Quesenberry
 04/05/2026
 commit_comment.txt
 
-docs: define unified 2D render pipeline contract seam across tilemap parallax sprite and vector tools
+docs: harden unified 2D render pipeline contract, validation, composition, and engine mappings for all four tools

docs/dev/COMMIT_COMMENT.txt

@@ -3,6 +3,4 @@ David Quesenberry
 04/05/2026
 next_command.txt
 
-Create BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS as a docs-only, repo-structured delta ZIP aligned to the approved PLAN_PR and output it to:
-
-HTML-JavaScript-Gaming-main/tmp/BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS_delta.zip
+APPLY_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS

docs/dev/NEXT_COMMAND.txt

@@ -5,23 +5,35 @@ change_summary.txt
 
 BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS summary
 
-- Created docs-only BUILD PR bundle for a unified 2D render pipeline contract.
-- Defined canonical top-level contract shape shared by:
+- Tightened the BUILD PR into a production-grade docs-only contract package.
+- Replaced the loose shared contract description with a formal contract family:
+  - toolbox.render.asset-document
+  - toolbox.render.composition-document
+- Added a required shared envelope with fixed versioning, producer, document, metadata, and payload requirements.
+- Added explicit shared schemas for metadata, assets, layers, and items.
+- Added locked tool-specific asset-document schemas for:
   - Tile Map Editor
   - Parallax Editor
   - Sprite Editor
   - Vector Asset Studio
-- Documented shared metadata requirements and ID stability rules.
-- Documented shared asset record rules with project-relative path normalization.
-- Documented normalized layer model and deterministic render ordering.
-- Added explicit tool-specific mapping notes for tilemap/parallax/sprite/vector payloads.
-- Defined runtime ownership boundaries and non-silent validation responsibilities.
-- Added validation rules and acceptance criteria for the contract seam.
-- Added incremental migration guidance designed to avoid breaking unrelated engine APIs.
+- Defined the formal render pipeline stages:
+  - load
+  - validate
+  - normalize
+  - resolve
+  - compose
+  - sequence
+  - render
+- Locked deterministic render order buckets and tie-break rules.
+- Locked engine seam ownership so runtime responsibilities and tool responsibilities are not guessed.
+- Added a mandatory validation layer with explicit rejection policy.
+- Added a formal composition document schema to assemble cross-tool scenes.
+- Tightened Codex execution instructions so the BUILD bundle is exact and non-drifting.
+- Added docs/dev/next_command.txt to make the follow-on APPLY step explicit.
 
 Guardrails honored:
 - Docs-first only
 - No implementation code
-- No 3D scope
-- No unrelated sample/game/tool changes
-- No engine redesign beyond contract seam
+- One PR purpose only
+- No unrelated engine or tool changes
+- 2D-only scope preserved

docs/dev/change_summary.txt

@@ -11,3 +11,4 @@ docs/dev/commit_comment.txt
 docs/dev/change_summary.txt
 docs/dev/validation_checklist.txt
 docs/dev/file_tree.txt
+docs/dev/next_command.txt

docs/dev/file_tree.txt

@@ -8,15 +8,22 @@ BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS validation checklist
 [x] Docs-only bundle created
 [x] No implementation code included
 [x] PLAN_PR -> BUILD_PR -> APPLY_PR workflow honored
-[x] One PR purpose only (render pipeline contract)
-[x] Unified top-level contract documented for all 4 tools
-[x] Shared metadata rules documented
-[x] Shared asset record rules documented
-[x] Normalized layer model documented
-[x] Deterministic render ordering documented
-[x] Tool-specific mapping notes included (tilemap/parallax/sprite/vector)
-[x] Runtime ownership boundaries documented
-[x] Validation rules and acceptance checklist documented
-[x] Incremental migration guidance documented
-[x] 2D-focused scope preserved
+[x] One PR purpose only retained
+[x] Shared contract envelope formalized
+[x] Shared metadata schema formalized
+[x] Shared asset schema formalized
+[x] Shared layer schema formalized
+[x] Shared item schema formalized
+[x] Tile Map Editor schema documented
+[x] Parallax Editor schema documented
+[x] Sprite Editor schema documented
+[x] Vector Asset Studio schema documented
+[x] Render pipeline stages formalized
+[x] Deterministic render bucket ordering formalized
+[x] Engine mappings locked explicitly
+[x] Validation rules documented with rejection policy
+[x] Allowed defaults restricted and documented
+[x] Composition document schema documented
+[x] Codex execution constraints tightened
+[x] 2D-only scope preserved
 [x] No unrelated architecture redesign introduced