Add Phase 4 execution plan and measurable quality gates

README.md

@@ -37,6 +37,8 @@ Operational limits:
 Docs:
 - `docs/release-checklist.md`
 - `docs/operations-runbook.md`
+- `docs/quality-gates.md`
+- `docs/phase4-execution-plan.md`
 
 CI:
 - `.gitea/workflows/ci.yml` runs syntax checks + full test suite on push/PR.

docs/phase4-execution-plan.md

@@ -0,0 +1,54 @@
+# Phase 4 Execution Plan
+
+Phase 4 milestone: `#3` - AAA SaaS Productization and UX Polish.
+
+## Objectives
+
+- Move Schemeta from prototype ergonomics to production-grade UX/UI quality.
+- Enforce measurable quality gates for beta and GA releases.
+- Sequence high-risk engine work (layout/routing) behind stable UX foundations.
+
+## Workstream Order
+
+1. `#23` AAA-00: Plan and quality gates
+2. `#15` AAA-01: Visual system redesign
+3. `#16` AAA-02: Fit-to-view and viewport behavior
+4. `#17` AAA-03: Layout engine v3
+5. `#18` AAA-04: Routing engine v3
+6. `#19` AAA-05: In-canvas editing overhaul
+7. `#20` AAA-06: Diagnostics UX 2.0
+8. `#21` AAA-07: Accessibility/responsive/keyboard pass
+9. `#22` AAA-08: SaaS + MCP production hardening
+
+## Dependency Graph
+
+- `#15` is prerequisite for high-fidelity baseline updates and consistent UI controls.
+- `#16` depends on `#15` token/layout primitives.
+- `#17` depends on `#16` viewport/fit behavior to evaluate perceived quality.
+- `#18` depends on `#17` placement decisions and semantic lanes.
+- `#19` depends on `#15` and should begin in parallel with late `#17` work where safe.
+- `#20` depends on `#19` interaction model for click-to-fix workflows.
+- `#21` runs continuously but final pass must occur after `#15/#19/#20`.
+- `#22` can run in parallel, but final contract freeze occurs after `#19/#20`.
+
+## Critical Path
+
+`#15 -> #16 -> #17 -> #18 -> #19 -> #20 -> #21 -> #22`
+
+## Risk Register
+
+1. Layout/routing regressions on dense circuits.
+   - Mitigation: expand fixture corpus, snapshot + metric thresholds, staged rollout.
+2. Visual redesign causing interaction regressions.
+   - Mitigation: preserve interaction test suite, baseline review checklist.
+3. Editor complexity inflation.
+   - Mitigation: keep single source of truth for selection/edit state, strict undo invariants.
+4. API/MCP compatibility drift.
+   - Mitigation: contract tests and explicit schema/api version policy enforcement.
+
+## Definition of Done (Phase 4)
+
+- All issues `#15-#23` closed with acceptance criteria verified.
+- Release checklist passes all beta and GA quality gates.
+- Browser regression and baseline review pass on representative fixtures (including dense analog).
+- API/MCP contract tests pass with versioned compatibility notes.

docs/quality-gates.md

@@ -0,0 +1,53 @@
+# Quality Gates
+
+This document defines measurable release gates for Schemeta.
+
+## Release Stages
+
+- Beta: feature complete, controlled rollout quality.
+- GA: production-grade quality, accessibility, and operational readiness.
+
+## Beta Gates
+
+1. Functional correctness
+   - `npm test` passes.
+   - `npm run test:ui` passes.
+2. Visual regression
+   - No unexpected screenshot diffs in `tests/baselines/ui`.
+   - Dense analog fixture remains under threshold:
+     - crossings = `0`
+     - overlaps = `0`
+     - detour <= `2.5`
+3. Interaction reliability
+   - Selection/deselection/isolate/reset flow verified.
+   - Undo/redo parity verified for component, pin, net, and symbol edits.
+4. API/MCP compatibility
+   - `api_version`/`schema_version` values present and documented.
+   - Compile/analyze envelopes remain backward compatible (additive policy).
+
+## GA Gates
+
+1. Accessibility
+   - Core workflows keyboard-operable.
+   - WCAG AA contrast on primary controls/text.
+2. Responsive UX
+   - Usable at 1280x720 and 1440x900 without clipping critical controls.
+3. Schematic readability
+   - No component-wire overlaps from auto layout/routing.
+   - Label overlap count near-zero on benchmark fixtures.
+4. Operational readiness
+   - Rate limiting + auth + health checks validated.
+   - Error telemetry includes structured codes and context.
+5. Data durability
+   - Save/load/restore and JSON roundtrip validated.
+   - MCP UI bundle + tool endpoints verified end-to-end.
+
+## CI Mapping
+
+- Always required:
+  - syntax checks
+  - `npm test`
+  - `npm run test:ui`
+- Release candidate required:
+  - checklist completion in `docs/release-checklist.md`
+  - intentional baseline updates reviewed and approved

docs/release-checklist.md

@@ -1,6 +1,9 @@
 # Schemeta Release Checklist
 
 Use this checklist before cutting a release tag.
+Reference docs:
+- `docs/quality-gates.md`
+- `docs/phase4-execution-plan.md`
 
 ## Pre-merge
 
@@ -12,6 +15,7 @@ Use this checklist before cutting a release tag.
 
 - [ ] `npm test` passes.
 - [ ] `npm run test:ui` passes.
+- [ ] Beta quality gates in `docs/quality-gates.md` are met.
 - [ ] Core smoke flow tested in UI:
   - [ ] Load sample
   - [ ] Edit component/pin/net/symbol
@@ -26,6 +30,7 @@ Use this checklist before cutting a release tag.
 - [ ] Visual baselines updated intentionally (`tests/baselines/ui`) and screenshot diff checks pass.
 - [ ] Labels remain legible at common zoom levels.
 - [ ] No major overlap/crossing regressions vs previous release baseline.
+- [ ] Dense analog fixture meets gate thresholds (`crossings=0`, `overlaps=0`, detour target).
 
 ## Security / Operations
 
@@ -37,6 +42,7 @@ Use this checklist before cutting a release tag.
   - [ ] `CORS_ORIGIN`
 - [ ] Rate limiting behavior manually validated.
 - [ ] Health endpoint checked in target environment.
+- [ ] Structured error telemetry checked for compile/analyze failures.
 
 ## Release Artifacts
 
@@ -44,3 +50,4 @@ Use this checklist before cutting a release tag.
 - [ ] `api_version` and `schema_version` changes reviewed/documented.
 - [ ] Changelog/release notes generated with notable UX/compat changes.
 - [ ] Tag pushed and release announcement links to milestone/issues.
+- [ ] GA gates in `docs/quality-gates.md` confirmed complete.