schemeta/docs/phase5-execution-plan.md

Phase 5 Execution Plan

Milestone: Phase 5 - Layout Robustness and JSON Import UX Hardening

Goals

1. Make drag/re-layout behavior measurable and regression-resistant.
2. Improve JSON import/apply reliability with validation-first messaging.
3. Ship richer fixture coverage and enforce readability budgets in CI.

Workstreams

1. QA harness and metrics artifact

   • Extend tests/ui-regression-runner.js to capture:
     • initial compile metrics
     • post-drag metrics
     • post-drag auto-tidy metrics
     • dense fixture metrics
   • Emit machine-readable artifact:
     • output/playwright/ui-metrics-report.json

2. Layout/readability quality budgets

   • Enforce thresholds in UI regression runner with env overrides:
     • UI_SAMPLE_MAX_*
     • UI_DRAG_MAX_*
     • UI_TIDY_MAX_*
     • UI_DENSE_MAX_*
   • Keep defaults tuned to current deterministic behavior.

3. JSON import UX hardening

   • Validate with /analyze before applying/importing JSON.
   • Block apply/import when validation has errors.
   • Surface first warning/error and path for faster correction.
   • Keep deterministic change summary after successful apply.

4. Fixture pack expansion

   • Add representative fixtures beyond the baseline audio example:
     • examples/dense-analog.json
     • examples/i2c-sensor-hub.json
     • examples/power-tree.json
   • Maintain warning-clean default sample (frontend/sample.schemeta.json).

Done Definition

1. npm test passes.
2. npm run test:ui passes with quality budgets.
3. output/playwright/ui-metrics-report.json is generated on every UI run.
4. Import/apply validation behavior is deterministic and user-visible.
5. Phase 5 issues #24-#29 are closed and milestone is closed.