diff --git a/README.md b/README.md index d069f9e..00cb05a 100644 --- a/README.md +++ b/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. diff --git a/docs/phase4-execution-plan.md b/docs/phase4-execution-plan.md new file mode 100644 index 0000000..bacd9d7 --- /dev/null +++ b/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. diff --git a/docs/quality-gates.md b/docs/quality-gates.md new file mode 100644 index 0000000..cab0fc8 --- /dev/null +++ b/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 diff --git a/docs/release-checklist.md b/docs/release-checklist.md index af11b28..d0c6aad 100644 --- a/docs/release-checklist.md +++ b/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.