prometeu-runtime/discussion/workflow/plans/PLN-0029-final-overlay-ci-validation-and-polish.md

id	ticket	title	status	created	completed	tags
PLN-0029	deferred-overlay-and-primitive-composition	Plan - Final Overlay CI Validation and Polish	accepted	2026-04-18		ci overlay runtime gfx validation

Objective

Run the final repository validation path for the deferred overlay/debug migration and perform the last compatibility, formatting, lint, and regression fixes required to close the thread cleanly.

Background

DEC-0016 changes visible runtime semantics and touches both specs and code paths around frame composition. A dedicated final-validation plan is needed so the implementation family can close on a clean CI signal rather than leaving integration fallout for later.

Scope

Included

• full-tree formatting, lint, and test validation
• stress-path smoke validation after overlay integration
• final cleanup fixes required to satisfy CI

Excluded

• new feature work outside the accepted overlay/debug migration

Execution Steps

Step 1 - Run focused validation before full CI

What: Catch local fallout in the touched areas before the full repository pass.

How:

• Run targeted tests for drivers, runtime, and pbxgen-stress.
• Inspect touched files for stale immediate-write assumptions or missed contract updates.

File(s):

• touched files from PLN-0026 through PLN-0028

Step 2 - Run final repository CI

What: Validate the migration end to end.

How:

• Run the repository validation path, including make ci.
• Fix any final formatting, lint, test, or generated-fixture fallout caused by the overlay/debug migration.
• Do not widen scope beyond the accepted thread.

File(s):

• repository-wide

Test Requirements

Unit Tests

• all relevant crate unit tests pass after the migration

Integration Tests

• runtime and stress/integration tests pass after the migration
• make ci passes

Manual Verification

• inspect the tree for residual direct-write assumptions or incomplete overlay propagation

Acceptance Criteria

• Targeted validation passes for the touched drivers/runtime/stress areas.
• make ci passes after the deferred overlay/debug migration family lands.
• No residual contract mismatch remains between spec text and code behavior in the touched thread.

Dependencies

• Source decision: DEC-0016
• Depends on PLN-0026, PLN-0027, and PLN-0028

Risks

• Final CI may surface unrelated renderer assumptions that still expect immediate-write semantics.
• Generated cartridge fixtures may drift if regeneration is forgotten during earlier plans.