Skip to content

Commit 2c5ec8c

Browse files
author
DavidQ
committed
docs: build 3D support layer + add roadmap guardrails
1 parent 19d3ca1 commit 2c5ec8c

11 files changed

Lines changed: 179 additions & 118 deletions

‎docs/dev/BIG_PICTURE_ROADMAP.md‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
1+
⚠️ RULE:
2+
This file is a status tracker only.
3+
ONLY modify bracket states [ ] [.] [x].
4+
Do NOT change structure or wording.
5+
6+
---
7+
18
# 🧭 Debug Platform & Ecosystem Roadmap
29

310
## Status Legend
@@ -73,10 +80,12 @@
7380
# 🧊 TRACK H — 3D DEBUG SUPPORT
7481

7582
- [.] Transform inspector
76-
- [.] Camera debug panel
77-
- [.] Render pipeline stages
78-
- [.] Collision overlays
79-
- [.] Scene graph inspector
83+
- [x] BUILD_PR_DEBUG_SURFACES_3D_SUPPORT
84+
- [ ] APPLY_PR_DEBUG_SURFACES_3D_SUPPORT
85+
- [ ] Camera debug panel
86+
- [ ] Render pipeline stages
87+
- [ ] Collision overlays
88+
- [ ] Scene graph inspector
8089

8190
---
8291

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 5 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,10 @@ MODEL: GPT-5.4-codex
22
REASONING: high
33

44
COMMAND:
5-
Create PLAN_PR_DEBUG_SURFACES_3D_SUPPORT
5+
Create BUILD_PR_DEBUG_SURFACES_3D_SUPPORT
66

77
Requirements:
8-
- Follow PLAN_PR -> BUILD_PR -> APPLY_PR
9-
- Docs-first only
10-
- One PR per purpose
11-
- Plan the first reusable 3D support layer for the debug surfaces platform
12-
- Define shared 3D panels, shared 3D providers, optional 3D presets, adapter boundaries, adoption models, naming conventions, and target structure
13-
- Keep the first version summary-level and opt-in
14-
- Exclude renderer-specific implementations, deep inspectors, and network support from this PR
15-
- Keep project-specific renderer/scene adapters outside the shared layer
16-
- Write outputs under docs/pr and docs/dev/reports
17-
- Put codex command and commit comment under docs/dev
18-
- Update BIG_PICTURE_ROADMAP.md by changing bracket states only
19-
- Package to <project folder>/tmp/PLAN_PR_DEBUG_SURFACES_3D_SUPPORT_delta.zip
8+
- Docs-only
9+
- Include guardrails file
10+
- Update BIG_PICTURE_ROADMAP.md (brackets only)
11+
- Package to <project folder>/tmp/BUILD_PR_DEBUG_SURFACES_3D_SUPPORT_delta.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
docs: plan reusable opt-in 3D support layer for debug surfaces
1+
docs: build 3D support layer and define guardrails for apply readiness

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
11
Next:
2-
BUILD_PR_DEBUG_SURFACES_3D_SUPPORT
2+
APPLY_PR_DEBUG_SURFACES_3D_SUPPORT

‎docs/dev/ROADMAP_GUARDRAILS.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# 🛡️ Roadmap Guardrails
2+
3+
## RULE
4+
docs/dev/BIG_PICTURE_ROADMAP.md is a status tracker.
5+
6+
Allowed:
7+
- Change [ ] [.] [x] only
8+
9+
Forbidden:
10+
- Any wording/structure change
11+
12+
## Validation
13+
- Headings unchanged
14+
- Only bracket diffs

‎docs/dev/reports/change_summary.txt‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,12 @@
1-
Created docs-only PLAN bundle for `PLAN_PR_DEBUG_SURFACES_3D_SUPPORT`.
1+
Created docs-only BUILD bundle for `BUILD_PR_DEBUG_SURFACES_3D_SUPPORT`.
22

3-
Included updates:
4-
- plan doc with shared 3D panels/providers/presets, boundaries, adoption, naming, and target structure
5-
- command and commit artifacts under docs/dev
6-
- roadmap bracket-state update only
7-
- report refresh under docs/dev/reports
3+
Included:
4+
- refreshed BUILD doc for 3D support contracts
5+
- new dedicated guardrails file
6+
- bracket-only roadmap state update
7+
- refreshed reports and packaging metadata
88

9-
Scope control:
10-
- docs-first only
11-
- one PR purpose only
9+
Scope controls maintained:
10+
- docs-only
1211
- no implementation code changes
13-
- renderer-specific, deep inspector, and network support remain out of scope
12+
- renderer-specific/deep-inspector/network scope excluded

‎docs/dev/reports/file_tree.txt‎

Lines changed: 9 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,9 @@
1-
PLAN_PR_DEBUG_SURFACES_3D_SUPPORT_delta/
2-
`-- docs/
3-
|-- dev/
4-
| |-- BIG_PICTURE_ROADMAP.md
5-
| |-- codex_commands.md
6-
| |-- commit_comment.txt
7-
| `-- reports/
8-
| |-- change_summary.txt
9-
| |-- file_tree.txt
10-
| `-- validation_checklist.txt
11-
`-- pr/
12-
`-- PLAN_PR_DEBUG_SURFACES_3D_SUPPORT.md
1+
BUILD_PR_DEBUG_SURFACES_3D_SUPPORT_delta.zip
2+
- docs/pr/BUILD_PR_DEBUG_SURFACES_3D_SUPPORT.md
3+
- docs/pr/BUILD_PR_DEBUG_SURFACES_3D_SUPPORT_GUARDRAILS.md
4+
- docs/dev/codex_commands.md
5+
- docs/dev/commit_comment.txt
6+
- docs/dev/BIG_PICTURE_ROADMAP.md
7+
- docs/dev/reports/change_summary.txt
8+
- docs/dev/reports/validation_checklist.txt
9+
- docs/dev/reports/file_tree.txt

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 11 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,14 @@
11
Validation Checklist
22

3-
[x] PLAN_PR -> BUILD_PR -> APPLY_PR flow is declared
4-
[x] Docs-first only (no implementation files changed)
5-
[x] One PR purpose only (3D support planning)
6-
[x] Shared 3D panel inventory is explicit
7-
[x] Shared 3D provider inventory is explicit
8-
[x] Optional 3D presets are defined
3+
[x] BUILD bundle is docs-only
4+
[x] Guardrails file is included
5+
[x] One PR purpose only (3D support BUILD)
6+
[x] Shared 3D panel inventory is present
7+
[x] Shared 3D provider inventory is present
8+
[x] Optional 3D presets are present
99
[x] Adapter boundaries are explicit
10-
[x] Adoption models are included
11-
[x] Naming conventions are included
12-
[x] Target structure is included
13-
[x] Renderer-specific implementation excluded
14-
[x] Deep inspectors excluded
15-
[x] Network support excluded
16-
[x] Project-specific adapters remain outside shared layer
17-
[x] BIG_PICTURE_ROADMAP.md updated via bracket-state changes only
18-
[x] BUILD next command is identified
10+
[x] Renderer-specific implementation scope excluded
11+
[x] Deep inspector scope excluded
12+
[x] Network scope excluded
13+
[x] BIG_PICTURE_ROADMAP.md updated by bracket changes only
14+
[x] Delta ZIP contains only BUILD-relevant docs

‎docs/pr/APPLY_PR_DEBUG_SURFACES_3D_SUPPORT.md‎

Lines changed: 10 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,12 @@
11
# APPLY_PR_DEBUG_SURFACES_3D_SUPPORT
22

3-
## Purpose
4-
5-
Apply the approved 3D support plan by creating the first shared 3D panels, providers, and optional presets for the debug surfaces platform.
6-
7-
## Apply Scope
8-
9-
### Create Shared 3D Panels
10-
- transform
11-
- camera
12-
- render stages
13-
- collision
14-
- scene graph
15-
16-
### Create Shared 3D Providers
17-
- transform summary
18-
- camera summary
19-
- render stage summary
20-
- collision volume summary
21-
- scene graph summary
22-
23-
### Create Optional Shared 3D Presets
24-
- 3d inspect
25-
- 3d render
26-
- 3d camera
27-
28-
### Keep Local
29-
- renderer-specific adapters
30-
- scene-specific extraction
31-
- project-specific debug visuals
32-
33-
## Apply Rules
34-
35-
- keep adoption opt-in
36-
- preserve existing platform patterns
37-
- keep shared logic renderer-agnostic
38-
- validate through a 3D-capable sample or staged adapter harness
3+
## Steps
4+
1. Create shared 3D providers (summary)
5+
2. Create panels consuming providers
6+
3. Register optional 3D presets
7+
4. Keep adapters local to project
8+
5. Validate with a 3D sample/adapters
9+
10+
## Rules
11+
- Use public APIs only
12+
- No renderer-specific logic in shared layer

‎docs/pr/BUILD_PR_DEBUG_SURFACES_3D_SUPPORT.md‎

Lines changed: 76 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,87 @@
11
# BUILD_PR_DEBUG_SURFACES_3D_SUPPORT
22

33
## Purpose
4+
Build a docs-only, implementation-ready bundle for the first reusable 3D support layer in the debug surfaces platform.
45

5-
Turn the 3D support plan into a docs-only build bundle for Codex.
6+
## Build Mode
7+
- Docs-only
8+
- One PR purpose only
9+
- No engine/runtime implementation files
610

7-
## Build Scope
11+
## Scope
12+
In scope:
13+
- Shared 3D panel inventory (summary-level)
14+
- Shared 3D provider inventory (read-only snapshots)
15+
- Optional shared 3D presets
16+
- Adapter boundary contracts
17+
- Adoption models and naming conventions
18+
- Validation and rollout guidance
819

9-
Define:
20+
Out of scope:
21+
- Renderer-specific implementations
22+
- Deep inspectors
23+
- Network/multiplayer support
24+
- Project-specific adapters in shared layer
1025

11-
- 3D panel inventory
12-
- 3D provider inventory
13-
- adapter boundaries
14-
- optional shared 3D presets
15-
- validation rules
16-
- rollout rules
26+
## Shared 3D Inventory
27+
Panels:
28+
- `panel.3d.transforms`
29+
- `panel.3d.camera`
30+
- `panel.3d.renderStages`
31+
- `panel.3d.collisions`
32+
- `panel.3d.sceneGraph`
1733

18-
## Required Deliverables
34+
Providers:
35+
- `provider.3d.transforms.snapshot`
36+
- `provider.3d.camera.snapshot`
37+
- `provider.3d.renderStages.snapshot`
38+
- `provider.3d.collisions.snapshot`
39+
- `provider.3d.sceneGraph.snapshot`
1940

20-
- authoritative target tree
21-
- panel/provider inventory
22-
- adapter ownership map
23-
- adoption models
24-
- validation checklist
25-
- rollback notes
26-
- codex command
27-
- commit comment
28-
- next command
41+
Optional presets:
42+
- `preset.3d.inspect`
43+
- `preset.3d.render`
44+
- `preset.3d.camera`
2945

30-
## Build Rules
46+
## Adapter Boundaries
47+
Shared layer responsibilities:
48+
- Define generic panel/provider/preset descriptors.
49+
- Provide registration seams and naming conventions.
3150

32-
- one PR purpose only
33-
- docs-first only
34-
- keep first 3D scope summary-level
35-
- no deep inspectors yet
36-
- no renderer-specific logic in shared layer
37-
- no network support in this PR
51+
Project/sample responsibilities:
52+
- Renderer-specific data extraction.
53+
- Scene-specific mapping.
54+
- Project-owned adapter implementations.
55+
56+
## Naming Conventions
57+
- Panels: `panel.3d.<domain>`
58+
- Providers: `provider.3d.<domain>.snapshot`
59+
- Presets: `preset.3d.<name>`
60+
61+
## Target Structure
62+
```text
63+
engine/
64+
debug/
65+
standard/
66+
threeD/
67+
panels/
68+
providers/
69+
presets/
70+
```
71+
72+
## Guardrails
73+
See `docs/pr/BUILD_PR_DEBUG_SURFACES_3D_SUPPORT_GUARDRAILS.md`.
74+
75+
## Validation Goals
76+
- Shared 3D inventory is explicit and reusable.
77+
- Shared layer remains renderer-agnostic.
78+
- Project-specific adapters stay outside shared layer.
79+
- Scope remains summary-level and opt-in.
80+
81+
## Rollout Notes
82+
1. Keep this BUILD docs-only.
83+
2. APPLY should implement in small slices:
84+
- provider contracts
85+
- panels
86+
- optional presets
87+
3. Preserve existing 2D debug behavior parity.

0 commit comments

Comments
 (0)