PSA/ee/docs/plans/2026-03-08-workflow-v1-hard-removal/PRD.md

# PRD — Workflow V1 Hard Removal

- Slug: `workflow-v1-hard-removal`
- Date: `2026-03-08`
- Status: Approved

## Summary

Remove the legacy AssemblyScript/code-editor workflow system and make Alga PSA workflow-v2-only. This includes deleting workflow v1 UI, actions, bootstrap/runtime wiring, seeded/template artifacts, and the legacy database schema. Existing v1 workflows will not be migrated. Templates remain a future product concept, but the current template library is removed because it only supports workflow v1.

## Problem

The repo currently carries two workflow systems with overlapping product surfaces:

- workflow v1: code-editor/runtime/template-library stack backed by `workflow_registrations`, `workflow_executions`, and related tables
- workflow v2: the current data-driven workflow designer/runtime

The v1 surfaces are now detritus. They are no longer the intended product path, but they still leak into:

- workflow control tabs
- server bootstraps
- exported action barrels
- database schema and seeds

That creates product confusion and ongoing maintenance risk. It also blocks a clean v2-native template system because the existing template library is coupled to the retired runtime.

## Goals

- Remove workflow v1 product surfaces from the app.
- Remove workflow v1 runtime and runner logic from shared/server bootstraps.
- Remove workflow v1 server actions, models, and exports.
- Drop workflow v1 database tables and related seeded/system data.
- Preserve and verify workflow v2 authoring, runs, schedules, and event surfaces.

## Non-goals

- Migrating existing v1 workflows to v2.
- Preserving legacy workflow definitions or template records.
- Delivering a workflow-v2-native template library in this change.
- Changing the workflow v2 product model beyond removing legacy tabs/buttons.

## Users and Primary Flows

### Primary users

- MSP admins who author or operate workflows
- developers maintaining workflow infrastructure

### Primary flows after the change

- Create and edit workflows only through the workflow v2 editor.
- Manage schedules, runs, events, and event catalog through workflow control.
- Start from scratch when creating workflows; no legacy template flow remains in this cut.

## UX / UI Notes

- Remove all v1-oriented UI surfaces, especially the current template library.
- Remove the `Template Library` tab from workflow control.
- Keep `/msp/workflow-editor` as the primary v2 authoring surface.
- Keep `/msp/workflow-control` for operational workflow-v2 tabs only.
- Any stale automation-hub/template links should redirect or be removed instead of leaving broken screens.

## Requirements

### Functional Requirements

- The app must no longer render or navigate to the workflow v1 editor or template-library UI.
- The workflow actions barrel must no longer export v1 workflow editor/runtime/template actions.
- Shared/server bootstrap must not initialize the workflow v1 runtime.
- Legacy consumers of `getWorkflowRuntime()` must be removed or migrated to workflow v2 equivalents.
- Database migrations must drop legacy workflow v1 tables and remove system/template data coupled to them.
- Tenant export/deletion/distribution code must stop referencing dropped v1 tables.
- Workflow v2 screens must continue to load after the v1 removal.

### Non-functional Requirements

- Removal must be coherent: no dead routes, dead menu entries, or dead exports left behind.
- The destructive DB migration must be idempotent enough for local/dev environments and safe for already-partially-cleaned states.
- Verification must include at least app boot plus focused workflow-v2 coverage.

## Data / API / Integrations

Legacy schema targeted for removal:

- `workflow_template_categories`
- `workflow_templates`
- `workflow_registrations`
- `workflow_registration_versions`
- `system_workflow_registrations`
- `system_workflow_registration_versions`
- `workflow_executions`
- `workflow_events`
- `workflow_event_processing`
- `workflow_snapshots`

Associated legacy APIs/codepaths targeted for removal:

- `workflow-editor-actions`
- `workflow-runtime-actions`
- `template-library-actions`
- shared v1 runtime/persistence modules under `shared/workflow/core`, `shared/workflow/init`, and `shared/workflow/persistence`

## Security / Permissions

- No new permissions are introduced.
- Existing workflow-v2 permissions remain authoritative.
- Dropping legacy tables must not break permission-gated workflow-v2 screens.

## Observability

- No new observability scope is added for this cleanup.
- Existing workflow-v2 logs and operational surfaces remain unchanged.

## Rollout / Migration

- This is a destructive retirement of workflow v1.
- Existing workflow v1 templates and definitions are intentionally deleted, not migrated.
- Database cleanup ships in the same cut as code removal.
- A future v2-native template library will be planned separately.

## Open Questions

- None blocking for this cut. Future v2 template design is intentionally deferred.

## Acceptance Criteria (Definition of Done)

- No product surface in the app exposes workflow v1 editor or template library.
- No workflow v1 runtime/bootstrap code executes during app startup.
- No workflow v1 action/module exports remain in active barrels.
- Legacy workflow v1 tables are dropped by migration and active code no longer queries them.
- Workflow v2 editor and workflow control operational tabs still load and function.