schemeta/docs/phase8-cutover-rollback.md

Phase 8 Cutover and Rollback Runbook

Goal

Move from legacy-first UI to React-first UI safely, with a deterministic rollback path.

Preconditions

• main branch green on:
  • npm run test
  • npm run test:ui
  • npm run frontend:react:check
• Milestone #7 issues required for cutover are accepted.
• Latest regression artifacts are present under output/playwright/.

Cutover Gate Command

Run this gate command before enabling React as default:

npm run phase8:cutover:check

It writes a machine-readable report to:

• output/phase8/cutover-check-report.json

Cutover Checklist

1. Confirm release candidate commit hash and tag target.
2. Run npm run phase8:cutover:check and archive report artifact.
3. Verify React path boots and legacy path still boots in dual-run.
4. Verify save/load/import/export compatibility on fixture corpus.
5. Confirm MCP tools still return stable API envelopes.
6. Publish release notes with known limitations and rollback trigger criteria.

Rollback Triggers

Rollback immediately if any occur post-cutover:

• New blocker in compile/apply loop.
• UI interaction regressions that break editing workflows.
• Crossings/overlaps/readability regressions above agreed thresholds.
• API/MCP contract break for compile/analyze/layout endpoints.

Rollback Procedure

1. Switch deployment back to previous stable tag.
2. Re-enable legacy-first UI mode.
3. Re-run:
   • npm run test
   • npm run test:ui
4. Open incident issue with:
   • failing commit/tag
   • regression screenshots
   • exact reproduction JSON
5. Keep React path available in non-default dual-run mode until fix lands.

Evidence to Attach to Release

• output/phase8/cutover-check-report.json
• output/playwright/ui-metrics-report.json
• Updated docs/release-checklist.md completion notes