# 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:

```bash
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