Migrate an existing workspace

Use this workflow only after existing-repository discovery identifies legacy planning organization that should move to the canonical numbered Basic, Structured, or Governed layout. Migration is an explicit repository transaction. Read-only inspection comes first; no review, doctor result, or planning recommendation starts migration automatically.

Start with a no-write structural check

Run the structural check before choosing destinations:

day-shift workspace migrate --check --format json

The check reports a protocol-v1 migration projection, each discovered work unit, its source paths, proposed or ambiguous workflow level, compatibility evidence, blockers, and a deterministic planDigest. It does not create parents, rewrite references, retire sources, acquire the write lock, or author migration records.

Supported compatibility inputs include an unnumbered Basic task root, an unnumbered Structured work root or direct task, a canonical numbered Governed root, the former Governed container-and-slices/ shape, a legacy top-level numbered root, and the former unnumbered Governed root. They are read inputs, not canonical new-write destinations. Unsupported files, symlinks, duplicate identities, ambiguous relationships, or incomplete task pairs remain blockers.

Inspect every source and destination

Emit the complete structural plan:

day-shift workspace migrate --plan --mapping <work-unit-id=structured> --root-order <work-unit-id=07> --task-sequence <work-unit-id:task-id=9> --format json

For every work unit, review:

• sourceRootPath, every inventoried source path, and any shared evidence that will be archived
• the selected Basic, Structured, or Governed level and whether the selection was inferred or explicit
• destinationRootPath, deterministic or explicit root order, and parent-local Structured task sequence
• every planned write, reference rewrite, metadata insertion, revision rebind, and legacy source retirement
• the durable migration-record path, transaction preconditions, recovery actions, findings, and exact planDigest

An ambiguous unit has no selected destination until --mapping resolves it. Basic and Structured roots need collision-free two-digit order. Direct Structured tasks need collision-free parent-local sequence. Missing, duplicate, contradictory, unsafe, or colliding selections block planning without writes.

Authorize only the exact plan

Keep the reviewed digest with the operator decision. Apply uses a fresh plan under the repository lock and succeeds only if that digest and every destination-presence or content-revision precondition still match:

day-shift workspace migrate --apply --mapping <work-unit-id=structured> --root-order <work-unit-id=07> --task-sequence <work-unit-id:task-id=9> --expected-plan-digest sha256:<reviewed-plan-digest> --confirm apply-workspace-migration --format json

The transaction stages complete replacement and retirement evidence under .day-shift/state/transactions/<transaction-id>/, writes canonical destinations in deterministic order, verifies postconditions, retires legacy sources, and writes the durable migration record. Canonical replacement is the irreversible boundary for that operation; before the first replacement, a failure is a no-write outcome. Do not edit a source or destination between plan and apply.

On a stale digest, precondition drift, path collision, changed mapping, or active lock, discard the authorization and run a fresh read-only plan. Do not retry the old digest and do not move or delete .day-shift/ paths manually.

Interpret the apply outcome

committed means every intended postcondition was verified. Inspect the reported canonical destinations, retired paths, durable migration record, and cleanup errors before continuing.

conflict or no-write means no canonical migration write completed. Preserve the reported evidence, inspect the changed path, and generate a fresh plan.

incomplete means at least one canonical replacement or retirement may have occurred. Stop normal writes. Preserve the returned transactionId, recoveryPath, and recoveryFingerprint; inspect current targets and staged evidence before choosing recovery. A cleanup error after verified commit also leaves inspectable transaction state and must not be treated as permission to delete it.

Recover an interrupted migration

Recovery is available only for a retained transaction whose current evidence still proves a safe action. Choose roll-forward when verified staged content should complete the reviewed migration. Choose restore when retained before-bytes can safely return every changed target to its pre-transaction state. Then bind the exact current fingerprint:

day-shift workspace migrate --recover roll-forward --transaction-id <transaction-id> --evidence-fingerprint sha256:<current-fingerprint> --actor <operator> --reason <bounded-recovery-reason> --confirm recover-workspace-migration --format json

Recovery revalidates the fingerprint after acquiring the lock, rejects live locks and diverged targets, writes a sanitized receipt under .day-shift/state/recovery-records/, verifies the chosen postconditions, and only then removes eligible operational state. A stale fingerprint, wrong transaction kind, missing staged evidence, conflicting receipt, or unsafe restore fails without recovery mutation. Reinspect and make a new decision; never substitute manual lock or transaction-directory deletion.

Compatibility and unsupported behavior

Schema-only --dry-run --target-schema-version 1 remains a separate compatibility lane. It does not perform structural planning, author nested runtime-acceptance policy, or move planning roots.

Partial-field migration, cross-family migration, automatic ambiguous mapping, migration triggered by review, implicit renaming during ordinary reads, and undocumented destructive cleanup are unsupported. Promotion demotion is also unsupported and is not a migration shortcut. Keep legacy paths readable until an exact supported transaction is reviewed and committed.

For transaction states, lock behavior, and recovery decisions, continue to Transaction and operational recovery. For command flags, use Operations and administration commands.