Skip to content

Commit c72c59e

Browse files
author
DavidQ
committed
docs: add engine maturity planning bundle, API inventory, versioning strategy, performance rules, documentation map, and roadmap status update
1 parent 4c13109 commit c72c59e

14 files changed

Lines changed: 416 additions & 38 deletions

‎docs/dev/BIG_PICTURE_ROADMAP.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -107,11 +107,11 @@ Do NOT change structure or wording.
107107

108108
# 🧠 TRACK J — ENGINE MATURITY
109109

110-
- [ ] Stable debug API
111-
- [ ] Plugin system
112-
- [ ] External documentation
113-
- [ ] Versioned contracts
114-
- [ ] Performance benchmarks
110+
- [.] Stable debug API
111+
- [.] Plugin system
112+
- [.] External documentation
113+
- [.] Versioned contracts
114+
- [.] Performance benchmarks
115115

116116
---
117117

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 2 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,3 @@
1-
MODEL: GPT-5.4-codex
1+
MODEL: GPT-5.4
22
REASONING: high
3-
4-
COMMAND:
5-
Create FINAL_ENGINE_PROMOTION bundle
6-
7-
Requirements:
8-
- docs only
9-
- no new features
10-
- focus on migration and stabilization
3+
COMMAND: Create BUILD_PR_ENGINE_MATURITY implementation bundle for HTML-JavaScript-Gaming. Respect PLAN_PR -> BUILD_PR -> APPLY_PR. Keep scope docs-first and surgical. Do not pollute engine core APIs. Promote only proven public debug surfaces. Define stable debug API seams, plugin lifecycle boundaries, versioned contract metadata, external documentation ownership, and performance benchmark entry points/rules. Preserve docs/pr history. Treat docs/dev/BIG_PICTURE_ROADMAP.md as bracket-only immutable structure except approved state transitions. Package output as repo-structured ZIP to <project folder>/tmp/BUILD_PR_ENGINE_MATURITY_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: finalize engine promotion bundle with migration and stabilization focus only
1+
docs: build engine maturity migration and stabilization bundle using proven public debug seams

‎docs/dev/ENGINE_MATURITY_API_INVENTORY.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Engine Maturity API Inventory
2+
3+
## Purpose
4+
Define the proven public debug surfaces that may be promoted, and the internal surfaces that remain non-public.
5+
6+
## Promotion Gate (required)
7+
A surface is promotable only if all are true:
8+
1. already used by multiple debug workflows
9+
2. behavior is deterministic and documented
10+
3. does not expose private state shape
11+
4. can be versioned with backward-compatibility notes
12+
13+
## Public Debug API Seams
14+
### Commands
15+
- command pack registration seam
16+
- command discovery/listing seam
17+
- standardized command output contract
18+
19+
### Panels
20+
- panel registration seam
21+
- panel descriptor metadata seam (`id`, `title`, `priority`, `enabled`)
22+
- panel summary render seam
23+
24+
### Providers
25+
- provider registration seam
26+
- read-only snapshot seam
27+
- bounded refresh/poll semantics
28+
29+
### Runtime Control
30+
- debug surface visibility seam (console/overlay)
31+
- deterministic debug render-order seam
32+
33+
## Plugin Lifecycle Seams
34+
- `register(context)`
35+
- `enable(context)`
36+
- `disable(context)`
37+
- `dispose(context)`
38+
39+
## Internal (Do Not Promote)
40+
- internal overlay composition internals
41+
- private runtime state containers
42+
- persistence internals
43+
- sample-specific wiring and hacks
44+
- experimental inspector internals
45+
46+
## Boundary Rule
47+
Promote seams, not implementation details.

‎docs/dev/ENGINE_MATURITY_DOCUMENTATION_MAP.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Engine Maturity Documentation Map
2+
3+
## Purpose
4+
Define ownership and canonical locations for engine-maturity docs.
5+
6+
## Canonical Ownership
7+
### PR History And Phase Artifacts
8+
- `docs/pr/PLAN_PR_ENGINE_MATURITY.md`
9+
- `docs/pr/BUILD_PR_ENGINE_MATURITY.md`
10+
- `docs/pr/APPLY_PR_ENGINE_MATURITY.md`
11+
12+
### Active Control Docs
13+
- `docs/dev/codex_commands.md`
14+
- `docs/dev/commit_comment.txt`
15+
- `docs/dev/next_command.txt`
16+
- `docs/dev/BIG_PICTURE_ROADMAP.md`
17+
- `docs/dev/ROADMAP_GUARDRAILS.md`
18+
19+
### Maturity Reference Docs
20+
- `docs/dev/ENGINE_MATURITY_API_INVENTORY.md`
21+
- `docs/dev/ENGINE_MATURITY_VERSIONING_STRATEGY.md`
22+
- `docs/dev/ENGINE_MATURITY_PERFORMANCE_RULES.md`
23+
- `docs/dev/ENGINE_MATURITY_DOCUMENTATION_MAP.md`
24+
25+
## Ownership Rule
26+
- normative migration/stabilization decisions live in `docs/pr/*ENGINE_MATURITY*`
27+
- operational controls live in `docs/dev/*`
28+
- avoid duplicate authoritative statements across files

‎docs/dev/ENGINE_MATURITY_PERFORMANCE_RULES.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Engine Maturity Performance Rules
2+
3+
## Purpose
4+
Define benchmark entry points and rules for debug-surface maturity.
5+
6+
## Benchmark Entry Points
7+
1. command execution latency
8+
2. overlay render/update frame cost
9+
3. provider snapshot/poll overhead
10+
4. panel show/hide/toggle cost
11+
5. preset apply/reset latency
12+
13+
## Measurement Rules
14+
- compare debug-disabled vs debug-enabled modes
15+
- measure cold-open and steady-state separately
16+
- capture environment/sample/scenario metadata
17+
- use consistent sample scenes for trend comparison
18+
19+
## Regression Rules
20+
- repeated regressions block maturity promotion
21+
- regressions require mitigation notes before apply closeout
22+
- avoid always-on heavy polling when debug surfaces are idle
23+
24+
## Acceptance
25+
- no user-visible debug latency regressions in normal workflows
26+
- no persistent high-cost background work when debug is disabled

‎docs/dev/ENGINE_MATURITY_VERSIONING_STRATEGY.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Engine Maturity Versioning Strategy
2+
3+
## Purpose
4+
Define contract metadata and lifecycle rules for promoted debug surfaces.
5+
6+
## Contract Metadata (required)
7+
Each promoted contract should declare:
8+
- `contractId`
9+
- `contractVersion`
10+
- `compatibility`
11+
- `backwardCompatible` (boolean)
12+
- `notes` (string)
13+
- `status` (`active|deprecated`)
14+
- `deprecatedSince` (optional)
15+
- `replacementContractId` (optional)
16+
17+
## Semantic Version Rules
18+
- MAJOR: breaking change
19+
- MINOR: additive compatible change
20+
- PATCH: non-breaking fixes/clarifications
21+
22+
## Compatibility Rules
23+
- MINOR/PATCH must preserve existing consumers
24+
- breaking changes require MAJOR + migration notes
25+
- deprecated contracts require replacement path
26+
27+
## Deprecation Window
28+
1. mark deprecated with replacement
29+
2. keep compatibility during transition window
30+
3. remove only on a MAJOR boundary

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1 @@
1-
Next:
2-
ENGINE_MATURITY_TRACK
1+
APPLY_PR_ENGINE_MATURITY

‎docs/dev/reports/change_summary.txt‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,15 @@
1-
Created docs-only FINAL_ENGINE_PROMOTION bundle.
1+
Created BUILD_PR_ENGINE_MATURITY docs-first implementation bundle.
22

3-
Updated:
4-
- PLAN/BUILD/APPLY final engine promotion docs
5-
- command and commit artifacts
6-
- reports and bundle file tree
3+
Updated scope:
4+
- stable public debug API seams
5+
- plugin lifecycle boundaries
6+
- versioned contract metadata requirements
7+
- external documentation ownership map
8+
- benchmark entry points and rules
79

810
Constraints enforced:
9-
- docs only
11+
- docs-first and surgical
1012
- no new features
11-
- migration and stabilization focus only
12-
- guardrails respected
13+
- no engine-core API pollution
14+
- preserve docs/pr history
15+
- roadmap updates constrained to bracket-state transitions only

‎docs/dev/reports/file_tree.txt‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,12 @@
1-
FINAL_ENGINE_PROMOTION_BUNDLE.zip
2-
- docs/pr/PLAN_PR_FINAL_ENGINE_PROMOTION.md
3-
- docs/pr/BUILD_PR_FINAL_ENGINE_PROMOTION.md
4-
- docs/pr/APPLY_PR_FINAL_ENGINE_PROMOTION.md
1+
BUILD_PR_ENGINE_MATURITY_delta.zip
2+
- docs/pr/PLAN_PR_ENGINE_MATURITY.md
3+
- docs/pr/BUILD_PR_ENGINE_MATURITY.md
4+
- docs/pr/APPLY_PR_ENGINE_MATURITY.md
5+
- docs/dev/ENGINE_MATURITY_API_INVENTORY.md
6+
- docs/dev/ENGINE_MATURITY_VERSIONING_STRATEGY.md
7+
- docs/dev/ENGINE_MATURITY_PERFORMANCE_RULES.md
8+
- docs/dev/ENGINE_MATURITY_DOCUMENTATION_MAP.md
9+
- docs/dev/BIG_PICTURE_ROADMAP.md
510
- docs/dev/ROADMAP_GUARDRAILS.md
611
- docs/dev/codex_commands.md
712
- docs/dev/commit_comment.txt

0 commit comments

Comments
 (0)