Document finish-on-v1 migration strategy for 2.0.0 upgrade

Expands the "Existing workflows" section in migration.md to explain:
- What happens to v1 data after upgrading (preserved in v1 tables)
- How v1 workflows complete (on v1 engine until terminal state)
- How to track v1 completion (workflow:v1:list command)
- Waterline dual-read capability (shows both v1 and v2 workflows)
- When it's safe to drop v1 tables (after all v1 workflows complete)
- Why finish-on-v1 is chosen over forced migration

This addresses the key blocker for 2.0.0 release: users now have a
clear, documented answer to "What happens to my v1 data when I upgrade?"

Part of resolving #227 (Phase 7 v1 import/migration strategy).

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: durable-workflow-ops

docs/migration.md

@@ -197,4 +197,67 @@ v2 adds history budgets that can automatically trigger continue-as-new when the
 
 ## Existing workflows
 
-Workflows started under v1 will continue to execute through v1 compatibility paths. New workflows started after upgrading will use v2 semantics. You do not need to migrate running workflow instances.
+### Finish-on-v1 strategy
+
+**Workflows started under v1 will continue to execute through v1 compatibility paths.** New workflows started after upgrading will use v2 semantics. You do not need to migrate running workflow instances.
+
+When you upgrade to 2.0:
+
+1. **v1 data is preserved** — The `stored_workflows`, `workflow_logs`, `workflow_signals`, `workflow_timers`, and `workflow_exceptions` tables remain intact
+2. **v1 workflows complete using v1 engine** — In-flight v1 workflows continue executing using the v1 replay engine until they reach a terminal state
+3. **v2 workflows use v2 engine** — All workflows started after upgrade use the v2 schema (`workflow_instances`, `workflow_runs`, `workflow_history_events`, etc.)
+4. **Waterline shows both** — The monitoring UI displays v1 and v2 workflows side-by-side
+
+### Tracking v1 workflow completion
+
+To see which v1 workflows are still active after upgrading:
+
+```bash
+php artisan workflow:v1:list
+```
+
+This command lists all v1 workflows that have not yet reached a terminal state (completed, failed, cancelled). Use it to track v1 workflow completion over time.
+
+Sample output:
+
+```
++--------------------------------------+---------------------+-----------+------------+
+| ID                                   | Class               | Status    | Created    |
++--------------------------------------+---------------------+-----------+------------+
+| 01J1234567890ABCDEFGHIJK             | App\OrderWorkflow   | running   | 2 days ago |
+| 01J9876543210ZYXWVUTSRQP             | App\InvoiceWorkflow | pending   | 1 day ago  |
++--------------------------------------+---------------------+-----------+------------+
+```
+
+### Waterline visibility
+
+After upgrading to 2.0, Waterline automatically shows workflows from both engines:
+
+- **v1 workflows** appear with their original `StoredWorkflow` data (class, status, logs, signals, exceptions)
+- **v2 workflows** appear with full v2 detail (runs, history events, timers, activities, search attributes)
+
+No configuration is needed — Waterline reads from both table sets and presents a unified view.
+
+### When to clean up v1 tables
+
+Once all v1 workflows have completed (confirmed by `workflow:v1:list` showing zero active workflows), you may optionally drop the v1 tables:
+
+```sql
+DROP TABLE IF EXISTS workflow_relationships;
+DROP TABLE IF EXISTS workflow_exceptions;
+DROP TABLE IF EXISTS workflow_timers;
+DROP TABLE IF EXISTS workflow_signals;
+DROP TABLE IF EXISTS workflow_logs;
+DROP TABLE IF EXISTS workflows;
+```
+
+**Important:** Do not drop these tables while any v1 workflows remain active. Doing so will cause v1 replay to fail and leave workflows stuck.
+
+### Why finish-on-v1?
+
+The finish-on-v1 strategy avoids forcing a data migration at upgrade time. v1 and v2 use fundamentally different storage models:
+
+- **v1** stores workflow state as a denormalized `workflows` row with related logs, signals, and timers
+- **v2** stores workflow state as event-sourced history with projections (`workflow_instances`, `workflow_runs`, `workflow_history_events`)
+
+Converting in-flight v1 workflows to v2 history would require reconstructing event sequences from v1 logs, which risks data loss and replay inconsistencies. The finish-on-v1 approach lets v1 workflows complete safely on their original engine while new work moves to v2 immediately.