Skip to content

V3 / V1 Retirement Guardrails v1

Status: accepted after B-V3-PLATFORM-WORKFLOW-POLISH-001 landed.

Execution sequencing lives in doc/product/V3_Migration_Execution_Tracker_v1.md. Use that tracker to decide whether a finding is a V3 migration blocker, a V1 compatibility-only issue, or a deferred roadmap task.

Decision

V3 production routes are the default migration target. V1 routes stay only as short-lived compatibility pages for demo/internal continuity and emergency fallback while the final cutover is validated.

Do not keep duplicate long-term frontend e2e coverage for V1 and V3. When a V3 workflow is covered by a production route and a stable E2E suite, the matching V1 E2E suite becomes compatibility-only and should not be part of the default frontend gate.

Validation Default

The default frontend_e2e CI job validates the V3 cutover path:

  • route-map and middleware behavior through v3-cutover.spec.ts
  • shell/persona behavior through v3-shell.spec.ts and v3-personas.spec.ts
  • user runtime flow through v3-workloads.spec.ts and v3-user-journey.spec.ts
  • compute/app launch surfaces through v3-compute-apps.spec.ts
  • storage/access/account surfaces through v3-storage-access-account.spec.ts
  • platform/admin/ops surfaces through v3-admin-platform.spec.ts

V1 Playwright specs remain runnable for local debugging or explicit compatibility checks, but broad V1 validation is no longer the default signal for release readiness after V3 cutover.

Compatibility-Only V1 Routes

These routes may remain visible during the final internal cutover window. Each one must have an exit condition; repeated operational use should become a V3 task instead of a V1 patch.

V1 area Compatibility reason V3 target / removal condition
/allocations/* Compatibility-only deep links for users who still have old allocation URLs bookmarked or in notifications/tasks. Detail URLs now cut over through /v3-prod/allocations/{id} and resolve to the owning workload while preserving panel intent. Remove V1 allocation pages after live kind/platform-control validation confirms terminal, metrics, storage, events/tasks, and app proxy open actions are stable on V3 workload detail.
/apps/instances/* Compatibility-only deep links for users who still have old app-instance URLs bookmarked or in notifications/tasks. Detail URLs now cut over through /v3-prod/apps/instances/{id} and resolve to the owning workload while preserving panel intent. Remove V1 app-instance pages after live kind validation confirms app open, metrics, lifecycle/events, member operations, and runtime actions are stable on V3 workload detail.
/admin/* known routes Operator fallback during the final internal cutover window. Remove from default navigation after kind validates Platform Ops/Lifecycle/Config/Evidence/Finance/IAM against live read models and repeated operator needs are represented as V3 tasks.
/developer/api-docs/* Utility docs pages until Stoplight Elements is integrated. Replace with the V3 developer/API reference task.
/proxy-launch and /terminal/* Compatibility entry points, not product pages. Keep as platform utility routes until protocol-specific V3 wrappers replace them.
/v3 Approved mock reference. Keep until V3 production visual and workflow parity is accepted.

Route-Map Guardrails

The cutover middleware must remain conservative:

  • default off unless NEXT_PUBLIC_V3_DEFAULT=1
  • pass through /api/*, /auth/*, /proxy-launch, /terminal, /v3, and /v3-prod
  • redirect only explicitly mapped routes
  • let unknown routes fall through
  • support sticky ?v1=1 opt-out during the internal cutover window
  • keep /v3 mock routes available for visual comparison

Unknown-route fallthrough is intentional. A missed route should show up as a coverage gap in doc/product/V3_Cutover_Route_Map_v1.md, not as a surprise redirect to an unrelated V3 page.

Frontend E2E Policy

Use V3 workflow tests as the release gate:

  • Prefer fail-closed V3 backend mocks for UI-only CI speed.
  • Use kind smoke tests for live integration validation.
  • Keep V1 tests out of default CI unless they cover an explicitly listed compatibility route.
  • Do not add new V1 E2E tests for migrated workflows.
  • Add or update a V3 test whenever the cutover route map changes.

The V1 UI can still be tested on demand by setting E2E_SPEC to the desired legacy Playwright specs when debugging a compatibility-only page.