PLAN_PR_ENGINE_MATURITY

DavidQ · DavidQ · commit 2587d07f34d0 · 2026-04-05T22:06:23.000-04:00
Defines the next engine-maturity planning layer for the debug platform.

Scope includes:
- stable debug API boundary
- plugin / extension model
- external documentation map
- versioned contract strategy
- performance benchmark rules

Docs-only PR. No runtime changes.
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -2,31 +2,11 @@ MODEL: GPT-5.3-codex
 REASONING: high
 
 COMMAND:
-Apply BUILD_PR_DEBUG_SURFACES_INSPECTORS exactly as defined.
-
-- Use docs/pr/BUILD_PR_DEBUG_SURFACES_INSPECTORS.md as implementation contract
-- Do not expand scope
-- Preserve engine/runtime separation
-- Do not modify unrelated files
-
-VALIDATION:
-- Inspector surfaces are read-only
-- Entity inspector works
-- Component inspector works
-- State diff viewer works
-- Timeline debugger works
-- Event stream viewer works
-- No runtime regressions
-- Frame buffer remains bounded
-
-ROADMAP UPDATE:
-Update docs/dev/BIG_PICTURE_ROADMAP.md using bracket-only edits:
-- Entity inspector -> [x]
-- Component inspector -> [x]
-- State diff viewer -> [x]
-- Timeline debugger -> [x]
-- Event stream viewer -> [x]
-
-OUTPUT:
-Create APPLY_PR_DEBUG_SURFACES_INSPECTORS delta ZIP at:
-<project folder>/tmp/APPLY_PR_DEBUG_SURFACES_INSPECTORS_delta.zip
+Create BUILD_PR_ENGINE_MATURITY
+
+REQUIREMENTS:
+- Build docs-only engine maturity bundle from PLAN_PR_ENGINE_MATURITY
+- Create required PR/dev/report files
+- Preserve boundaries and roadmap protection rules
+- Bracket-only roadmap state edits when needed
+- Package to <project folder>/tmp/BUILD_PR_ENGINE_MATURITY_delta.zip
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,11 +1 @@
-APPLY_PR_DEBUG_SURFACES_INSPECTORS
-
-Applies the approved inspector layer:
-- Entity inspector
-- Component inspector
-- State diff viewer
-- Timeline debugger
-- Event stream viewer
-
-Preserves read-only behavior, bounded frame history, optional debug surfaces,
-and roadmap bracket-only updates for Track I.
+docs: build engine maturity docs bundle from PLAN with stable seams, lifecycle boundaries, versioning, docs ownership, and benchmark rules
diff --git a/docs/dev/ENGINE_MATURITY_API_INVENTORY.md b/docs/dev/ENGINE_MATURITY_API_INVENTORY.md
@@ -1,47 +1,21 @@
 # Engine Maturity API Inventory
 
-## Purpose
-Define the proven public debug surfaces that may be promoted, and the internal surfaces that remain non-public.
-
-## Promotion Gate (required)
-A surface is promotable only if all are true:
-1. already used by multiple debug workflows
-2. behavior is deterministic and documented
-3. does not expose private state shape
-4. can be versioned with backward-compatibility notes
-
-## Public Debug API Seams
-### Commands
-- command pack registration seam
-- command discovery/listing seam
-- standardized command output contract
-
-### Panels
-- panel registration seam
-- panel descriptor metadata seam (`id`, `title`, `priority`, `enabled`)
-- panel summary render seam
-
-### Providers
-- provider registration seam
-- read-only snapshot seam
-- bounded refresh/poll semantics
-
-### Runtime Control
-- debug surface visibility seam (console/overlay)
-- deterministic debug render-order seam
-
-## Plugin Lifecycle Seams
-- `register(context)`
-- `enable(context)`
-- `disable(context)`
-- `dispose(context)`
-
-## Internal (Do Not Promote)
+## Public Seams (Promotable)
+- command registration/discovery/execution output contract
+- panel registration and descriptor contract
+- provider registration and read-only snapshot contract
+- debug visibility and deterministic render-order control seams
+- plugin lifecycle seam (`register/enable/disable/dispose`)
+
+## Internal (Not Promoted)
 - internal overlay composition internals
 - private runtime state containers
 - persistence internals
-- sample-specific wiring and hacks
-- experimental inspector internals
+- sample-specific hacks/bindings
+
+## Transitional
+- compatibility shims for legacy paths only when required
+- deprecation notes with replacement path
 
-## Boundary Rule
-Promote seams, not implementation details.
+## Promotion Gate
+Promote only proven, documented, deterministic surfaces that do not leak private state shape.
diff --git a/docs/dev/ENGINE_MATURITY_DOCUMENTATION_MAP.md b/docs/dev/ENGINE_MATURITY_DOCUMENTATION_MAP.md
@@ -1,28 +1,17 @@
 # Engine Maturity Documentation Map
 
-## Purpose
-Define ownership and canonical locations for engine-maturity docs.
-
-## Canonical Ownership
-### PR History And Phase Artifacts
+## Canonical Files
 - `docs/pr/PLAN_PR_ENGINE_MATURITY.md`
 - `docs/pr/BUILD_PR_ENGINE_MATURITY.md`
 - `docs/pr/APPLY_PR_ENGINE_MATURITY.md`
-
-### Active Control Docs
-- `docs/dev/codex_commands.md`
-- `docs/dev/commit_comment.txt`
-- `docs/dev/next_command.txt`
-- `docs/dev/BIG_PICTURE_ROADMAP.md`
-- `docs/dev/ROADMAP_GUARDRAILS.md`
-
-### Maturity Reference Docs
 - `docs/dev/ENGINE_MATURITY_API_INVENTORY.md`
 - `docs/dev/ENGINE_MATURITY_VERSIONING_STRATEGY.md`
 - `docs/dev/ENGINE_MATURITY_PERFORMANCE_RULES.md`
 - `docs/dev/ENGINE_MATURITY_DOCUMENTATION_MAP.md`
 
-## Ownership Rule
-- normative migration/stabilization decisions live in `docs/pr/*ENGINE_MATURITY*`
-- operational controls live in `docs/dev/*`
-- avoid duplicate authoritative statements across files
+## Ownership
+- `docs/pr`: phase history and implementation intent
+- `docs/dev`: active controls + maturity reference docs
+
+## Rule
+Do not duplicate normative guidance across multiple files; cross-link to canonical source.
diff --git a/docs/dev/ENGINE_MATURITY_PERFORMANCE_RULES.md b/docs/dev/ENGINE_MATURITY_PERFORMANCE_RULES.md
@@ -1,26 +1,17 @@
 # Engine Maturity Performance Rules
 
-## Purpose
-Define benchmark entry points and rules for debug-surface maturity.
-
 ## Benchmark Entry Points
 1. command execution latency
 2. overlay render/update frame cost
-3. provider snapshot/poll overhead
+3. provider polling/snapshot overhead
 4. panel show/hide/toggle cost
 5. preset apply/reset latency
 
 ## Measurement Rules
-- compare debug-disabled vs debug-enabled modes
+- compare debug-disabled and debug-enabled modes
 - measure cold-open and steady-state separately
-- capture environment/sample/scenario metadata
-- use consistent sample scenes for trend comparison
+- record environment/sample/scenario metadata
 
 ## Regression Rules
 - repeated regressions block maturity promotion
-- regressions require mitigation notes before apply closeout
-- avoid always-on heavy polling when debug surfaces are idle
-
-## Acceptance
-- no user-visible debug latency regressions in normal workflows
-- no persistent high-cost background work when debug is disabled
+- no always-on heavy polling when debug is idle
diff --git a/docs/dev/ENGINE_MATURITY_VERSIONING_STRATEGY.md b/docs/dev/ENGINE_MATURITY_VERSIONING_STRATEGY.md
@@ -1,30 +1,20 @@
 # Engine Maturity Versioning Strategy
 
-## Purpose
-Define contract metadata and lifecycle rules for promoted debug surfaces.
-
-## Contract Metadata (required)
+## Contract Metadata
 Each promoted contract should declare:
 - `contractId`
 - `contractVersion`
-- `compatibility`
-  - `backwardCompatible` (boolean)
-  - `notes` (string)
+- `compatibility` (`backwardCompatible`, `notes`)
 - `status` (`active|deprecated`)
 - `deprecatedSince` (optional)
 - `replacementContractId` (optional)
 
-## Semantic Version Rules
-- MAJOR: breaking change
-- MINOR: additive compatible change
-- PATCH: non-breaking fixes/clarifications
-
-## Compatibility Rules
-- MINOR/PATCH must preserve existing consumers
-- breaking changes require MAJOR + migration notes
-- deprecated contracts require replacement path
+## SemVer Rules
+- MAJOR: breaking
+- MINOR: additive/backward-compatible
+- PATCH: non-breaking fix/clarification
 
-## Deprecation Window
-1. mark deprecated with replacement
-2. keep compatibility during transition window
-3. remove only on a MAJOR boundary
+## Deprecation
+- mark deprecated with replacement guidance
+- keep transition window
+- remove only on MAJOR boundary
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1 +1 @@
-Create PLAN_PR_ENGINE_MATURITY
+APPLY_PR_ENGINE_MATURITY
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,10 +1,13 @@
-Applies BUILD_PR_DEBUG_SURFACES_INSPECTORS exactly as approved.
+Created BUILD_PR_ENGINE_MATURITY docs-only bundle from PLAN.
 
-Confirms:
-- inspector layer integrated
-- read-only inspection preserved
-- bounded frame history preserved
-- event stream remains passive
-- roadmap updated by bracket-only state changes in Track I
+Updated:
+- BUILD/APPLY PR docs for engine maturity
+- maturity API/versioning/performance/docs-map references
+- active codex/commit/next-command docs
+- reports and file tree
 
-No out-of-scope changes permitted.
+Constraints enforced:
+- docs-only
+- no runtime code changes
+- preserve public/internal/transitional boundaries
+- preserve roadmap guardrails (bracket-only if edited)
diff --git a/docs/dev/reports/file_tree.txt b/docs/dev/reports/file_tree.txt
@@ -1,7 +1,13 @@
-docs/pr/APPLY_PR_DEBUG_SURFACES_INSPECTORS.md
-docs/dev/codex_commands.md
-docs/dev/commit_comment.txt
-docs/dev/next_command.txt
-docs/dev/reports/change_summary.txt
-docs/dev/reports/validation_checklist.txt
-docs/dev/reports/file_tree.txt
+BUILD_PR_ENGINE_MATURITY_delta.zip
+- docs/pr/BUILD_PR_ENGINE_MATURITY.md
+- docs/pr/APPLY_PR_ENGINE_MATURITY.md
+- docs/dev/ENGINE_MATURITY_API_INVENTORY.md
+- docs/dev/ENGINE_MATURITY_VERSIONING_STRATEGY.md
+- docs/dev/ENGINE_MATURITY_PERFORMANCE_RULES.md
+- docs/dev/ENGINE_MATURITY_DOCUMENTATION_MAP.md
+- docs/dev/codex_commands.md
+- docs/dev/commit_comment.txt
+- docs/dev/next_command.txt
+- docs/dev/reports/change_summary.txt
+- docs/dev/reports/file_tree.txt
+- docs/dev/reports/validation_checklist.txt
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,11 +1,13 @@
-[ ] APPLY scope matches approved BUILD scope
-[ ] No runtime mutation APIs added
-[ ] Entity inspector works
-[ ] Component inspector works
-[ ] State diff viewer works
-[ ] Timeline debugger works
-[ ] Event stream viewer works
-[ ] Frame buffer bounded
-[ ] Existing samples still run
-[ ] No unrelated files changed
-[ ] BIG_PICTURE_ROADMAP updated with bracket-only edits
+Validation Checklist
+
+[x] PLAN_PR -> BUILD_PR -> APPLY_PR flow preserved
+[x] Bundle is docs-only
+[x] No runtime code files changed in this step
+[x] Stable debug API seams documented
+[x] Plugin lifecycle boundaries documented
+[x] Versioned contract metadata documented
+[x] External documentation ownership documented
+[x] Performance benchmark entry points/rules documented
+[x] Public/internal/transitional boundaries preserved
+[x] BIG_PICTURE_ROADMAP.md structure preserved
+[x] Bracket-only roadmap edits used if needed
diff --git a/docs/pr/APPLY_PR_ENGINE_MATURITY.md b/docs/pr/APPLY_PR_ENGINE_MATURITY.md
@@ -1,33 +1,22 @@
 # APPLY_PR_ENGINE_MATURITY
 
 ## Purpose
-Define how the later implementation PR should be applied after the maturity build slice is accepted.
+Apply the approved engine maturity migration/stabilization surfaces defined by PLAN and BUILD.
 
 ## Apply Rules
-- Apply only approved surfaces from the plan/build docs.
-- Do not widen public APIs during apply.
-- Do not modify roadmap wording or structure.
-- Keep changes small, surgical, and reversible.
-- Preserve docs history in `docs/pr/`.
+- apply only approved seams
+- keep changes surgical and reversible
+- do not widen public API surface during apply
+- preserve existing behavior parity
 
 ## Apply Sequence
-1. Promote approved stable debug APIs.
-2. Add plugin lifecycle seams with internal isolation.
-3. Attach version metadata/compatibility documentation.
-4. Wire benchmark entry points or benchmark hooks if in scope.
-5. Refresh docs/dev reports and active controls.
+1. promote approved stable debug API seams
+2. apply plugin lifecycle boundaries
+3. attach version metadata and compatibility notes
+4. apply benchmark entry points/rules
+5. refresh docs/dev control and reports
 
 ## Verification
-- Public/internal boundary still matches inventory.
-- Existing debug console/overlay behavior remains intact.
-- No sample-level hacks are reclassified as engine contracts.
-- Versioning/deprecation notes exist for promoted surfaces.
-- Benchmark expectations are measurable and documented.
-
-## Rollback Guidance
-- Revert newly promoted public surfaces first.
-- Remove plugin-facing exports before touching internals.
-- Preserve docs/reports for post-mortem comparison.
-
-## Done Condition
-The APPLY PR is complete when the promoted maturity surfaces are implemented without breaking current debug usage and all docs/dev control files reflect the applied state.
+- public/internal/transitional boundaries remain intact
+- no runtime regressions
+- maturity docs and contract metadata are consistent
diff --git a/docs/pr/BUILD_PR_ENGINE_MATURITY.md b/docs/pr/BUILD_PR_ENGINE_MATURITY.md
diff --git a/docs/pr/PLAN_PR_ENGINE_MATURITY.md b/docs/pr/PLAN_PR_ENGINE_MATURITY.md

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Create PLAN_PR_ENGINE_MATURITY`
	`1`	`+APPLY_PR_ENGINE_MATURITY`