---
id: PLN-0029
ticket: deferred-overlay-and-primitive-composition
title: Plan - Final Overlay CI Validation and Polish
status: accepted
created: 2026-04-18
completed:
tags: [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.