Add Phase 8 React+ELK refactor execution plan

docs/phase8-react-elk-refactor-plan.md

@@ -0,0 +1,95 @@
+# Phase 8 Execution Plan: React + ELK Core Refactor
+
+## Objective
+Deliver the largest Schemeta refactor to date: migrate the frontend to a robust React architecture, replace fragile placement behavior with ELK-driven layout, harden routing/labeling readability, and establish production-grade quality gates.
+
+This phase is OSS-only and budget-neutral.
+
+## Non-Goals
+- No paid/proprietary graph SDKs.
+- No API contract break for `/compile`, `/analyze`, `/layout/auto`, `/layout/tidy`.
+- No regression of current JSON schema compatibility.
+
+## Architecture Target
+- Frontend: React + TypeScript + Vite.
+- Interaction layer: React Flow primitives for node/selection/viewport interactions.
+- Layout: `elkjs` as primary placement engine.
+- Routing: Schemeta incremental router with deterministic tie-net fallback.
+- State: deterministic centralized action pipeline (undo/redo transaction model).
+
+## Work Breakdown (Milestone #7)
+- #37 P8-01 Frontend architecture migration to React + TS + Vite
+- #38 P8-02 State model refactor with deterministic action pipeline
+- #39 P8-03 Canvas subsystem rewrite with React Flow contracts
+- #40 P8-04 ELK integration and constraints mapping
+- #41 P8-05 Routing engine revamp (incremental reroute)
+- #42 P8-06 Deterministic label placement and collision avoidance
+- #43 P8-07 Symbol readability and pin-density standards
+- #44 P8-08 JSON editor power-tool upgrade (schema-aware + diff apply)
+- #45 P8-09 QA hardening (visual/readability gates)
+- #46 P8-10 Cutover, migration, rollback
+
+## Delivery Sequence (Critical Path)
+1. Foundation
+   - Complete #37 (React app shell) and #38 (state architecture).
+   - Exit criteria: feature-parity shell + deterministic action store.
+2. Interaction rewrite
+   - Complete #39 on top of #37/#38.
+   - Exit criteria: drag/multi-select/pan/zoom/edit stable and undoable.
+3. Layout core
+   - Complete #40 with adapter boundaries for constraints.
+   - Exit criteria: ELK-based autolayout deterministic on fixtures.
+4. Routing core
+   - Complete #41 with local reroute and deterministic fallback behavior.
+   - Exit criteria: moved components reroute only affected nets.
+5. Readability system
+   - Complete #42 + #43 for labels/pin-density constraints.
+   - Exit criteria: baseline fixtures have no label/pin overlap failures.
+6. Power-user JSON workflow
+   - Complete #44 for schema-aware editing and safe apply previews.
+7. Quality gates + ship safety
+   - Complete #45 + #46; run cutover checklist.
+
+## Technical Design Rules
+- Determinism first: all ordered traversals sort by stable keys.
+- Incremental operations default: no full relayout on drag/edit unless explicit.
+- Readability constraints are hard constraints, not best-effort hints.
+- Feature flags for risky changes during dual-run period.
+
+## Quality Gates (Phase 8 Additions)
+In addition to existing crossings/overlaps/detour metrics:
+- Label collisions must be 0 in baseline fixtures.
+- Pin text collisions must be 0 in baseline fixtures.
+- Component overlap must remain 0.
+- Drag action must not move untouched components.
+- Snapshot test matrix across viewport sizes and render modes.
+
+## Risks and Mitigation
+- Risk: React migration stalls on parity gaps.
+  - Mitigation: keep legacy UI in dual-run until parity checklist passes.
+- Risk: ELK mapping mismatch with custom constraints.
+  - Mitigation: fallback mapping with explicit unsupported-constraint diagnostics.
+- Risk: routing regressions after layout changes.
+  - Mitigation: incremental router tests and stress fixtures in CI.
+- Risk: test flakiness due to persisted state.
+  - Mitigation: force deterministic test bootstrapping and storage resets.
+
+## Performance Budgets
+- Compile latency p95 (sample): <= 180ms local.
+- Drag-to-reroute p95 (affected nets only): <= 120ms local.
+- Auto layout p95 (medium fixture): <= 600ms local.
+
+## Release Readiness Checklist
+- All milestone issues closed.
+- CI green for unit + UI + readability metrics.
+- Dual-run comparison report attached.
+- Rollback validated with documented steps.
+- Release notes include migration caveats and known limitations.
+
+## Definition of Done
+Phase 8 is done only when:
+- React UI is default and legacy path can be disabled safely.
+- ELK placement is primary in production path.
+- Readability gates are enforced in CI.
+- Drag/edit interactions are deterministic and locally incremental.
+- JSON/AI workflows are schema-aware and operator-safe.