refactor(migration): 回填 Migration Phase Strategy 體系（PR-D）

A v3.0.1 把 orchestrator 的 11 個 phase 抽成可注入的 Phase 物件，B 仍是
1107 行單體、以 'phase_' . $current 字串魔法分派、completed 甚至 inline
在 tick() 裡。本 commit 對齊：

新增 13 檔
- includes/migration/interface-migration-phase.php
- includes/migration/class-tmdo-migration-phase-base.php（log/get_managed_keys/
  execute_bulk_pivot/values_loose_equal 等共用 helper）
- includes/migration/phases/ 11 個 phase 類別

orchestrator 1107 → 640 行
- tick() 改 make_phase() 工廠 + $phase->execute($job)
- 移除 final、self::ENTITY_TYPE → static::（A v3.3.0 late static binding）
- 保留 B 原有的 '✓ %s (%.2fs)' 耗時 log（改為 tick 自行量測，A 版已簡化掉）
- 公開介面（preflight/start/tick/get_status/cancel/resume/needs_attention/
  cron_tick）經 diff 確認與 A 完全一致，呼叫端零影響

連帶
- Schema_Manager 補 table_exists 的 request-scoped cache 與
  flush_table_exists_cache()（A v3.1.6 + v3.4.6），Phase 測試需要它
- back-compat 補 12 個 Phase 類別的 WPDO_ alias
- 移植 MigrationPhaseTest + MigrationPhaseRemainingTest（527 行）

測試隔離差異（B 的 unit bootstrap 會載入 Member_Fields / Post_Fields，
A 的不會）：MigrationPhaseRemainingTest 的 setUp 需額外清空 Entity_Registry
與 wpdo_register_entity_fields listener，否則 install_schema 會真的走進
dbDelta。MigrationPhaseTest 的 interface 斷言改用 TMDO_ 正式名稱
（PHP 無法 class_alias 介面，且該契約是核心內部擴充點）。

unit 451 / integration 398 GREEN

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TbG1keQQ7XBa7qMQY16KCY

tests/bootstrap.php

@@ -600,6 +600,19 @@ require_once TMDO_PATH . 'includes/adapters/class-tmdo-adapter-term.php';
 require_once TMDO_PATH . 'includes/adapters/class-tmdo-adapter-comment.php';
 
 // Migration Orchestrator (needs Entity_Registry).
+require_once TMDO_PATH . 'includes/migration/interface-migration-phase.php';
+require_once TMDO_PATH . 'includes/migration/class-tmdo-migration-phase-base.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-diagnose.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backup.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-demote.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-install-schema.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backfill-bulk.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backfill-unserialize.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-promote-shadow.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-verify-sample.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-promote-aeav.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-cleanup.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-completed.php';
 require_once TMDO_PATH . 'includes/migration/class-tmdo-migration-orchestrator.php';
 require_once TMDO_PATH . 'includes/migration/class-tmdo-post-migration.php';
 

tests/integration/bootstrap.php

@@ -569,6 +569,19 @@ require_once TMDO_PATH . 'includes/adapters/class-tmdo-adapter-post.php';
 require_once TMDO_PATH . 'includes/adapters/class-tmdo-adapter-user.php';
 require_once TMDO_PATH . 'includes/adapters/class-tmdo-adapter-term.php';
 require_once TMDO_PATH . 'includes/adapters/class-tmdo-adapter-comment.php';
+require_once TMDO_PATH . 'includes/migration/interface-migration-phase.php';
+require_once TMDO_PATH . 'includes/migration/class-tmdo-migration-phase-base.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-diagnose.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backup.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-demote.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-install-schema.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backfill-bulk.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backfill-unserialize.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-promote-shadow.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-verify-sample.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-promote-aeav.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-cleanup.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-completed.php';
 require_once TMDO_PATH . 'includes/migration/class-tmdo-migration-orchestrator.php';
 require_once TMDO_PATH . 'includes/migration/class-tmdo-post-migration.php';
 require_once TMDO_PATH . 'modules/options/class-tmdo-options-manager.php';

tests/unit/MigrationPhaseRemainingTest.php

@@ -0,0 +1,282 @@
+<?php
+declare(strict_types=1);
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Unit tests for the 5 migration phases not covered in MigrationPhaseTest.php
+ * (P1-11): Diagnose, Install_Schema, Backfill_Bulk, Backfill_Unserialize,
+ * Verify_Sample.
+ *
+ * All engine dependencies (WPDO_Schema_Manager, WPDO_Migration_Orchestrator,
+ * WPDO_Entity_Migration_Engine, WPDO_Hook_Bus) use the real classes loaded via
+ * composer autoload. The $wpdb stub returns null/[] for all DB calls, giving
+ * zero-row results sufficient to exercise the logic paths under test.
+ */
+class MigrationPhaseRemainingTest extends TestCase {
+
+	/** @var object Original $wpdb saved for restoration. */
+	private object $original_wpdb;
+
+	protected function setUp(): void {
+		global $wpdb;
+		$this->original_wpdb    = $wpdb;
+		$GLOBALS['_wp_options'] = array();
+		WPDO_Mode_Manager::reset_cache();
+
+		// Provide a fresh $wpdb with all methods the phases under test require,
+		// regardless of which prior test may have left a broken stub.
+		$wpdb = new class {
+			public string $prefix     = 'wp_';
+			public string $users      = 'wp_users';
+			public string $usermeta   = 'wp_usermeta';
+			public string $postmeta   = 'wp_postmeta';
+			public string $options    = 'wp_options';
+			public string $last_error = '';
+			public array  $queries    = [];
+			public function prepare( string $sql, ...$args ): string {
+				$i = 0;
+				return preg_replace_callback( '/%[sd]/', function () use ( &$i, $args ) {
+					return (string) ( $args[ $i++ ] ?? '?' );
+				}, $sql );
+			}
+			public function get_var( string $sql ): ?string { return null; }
+			public function get_col( string $sql ): array { return []; }
+			public function get_results( string $sql, $output = null ): array { return []; }
+			public function query( string $sql ): int|bool { $this->queries[] = $sql; return 1; }
+			public function insert( string $t, array $d, $f = null ): int|false { return 1; }
+			public function get_charset_collate(): string { return ''; }
+		};
+
+		// Reset Schema_Manager request-scoped cache so table_exists() hits $wpdb each test.
+		$ref  = new ReflectionClass( WPDO_Schema_Manager::class );
+		$prop = $ref->getProperty( 'table_exists_cache' );
+		$prop->setAccessible( true );
+		$prop->setValue( null, array() );
+
+		// The unit bootstrap loads Member_Fields / Post_Fields, which register entity
+		// groups at include time. These phases assert "no groups registered" behaviour,
+		// so clear the registry to isolate them from that ambient state.
+		$reg = new ReflectionClass( WPDO_Entity_Registry::class );
+		foreach ( array( 'groups', 'field_index' ) as $name ) {
+			$p = $reg->getProperty( $name );
+			$p->setAccessible( true );
+			$p->setValue( null, array() );
+		}
+
+		// Install_Schema re-fires wpdo_register_entity_fields, which would re-populate
+		// the registry from those same listeners — drop them for the duration.
+		$this->saved_field_listeners                            = $GLOBALS['_wp_filter_callbacks']['wpdo_register_entity_fields'] ?? array();
+		$GLOBALS['_wp_filter_callbacks']['wpdo_register_entity_fields'] = array();
+		WPDO_Entity_Registry::clear_pending_schemas();
+	}
+
+	/**
+	 * Listeners removed in setUp() and restored in tearDown().
+	 *
+	 * @var array
+	 */
+	private array $saved_field_listeners = array();
+
+	protected function tearDown(): void {
+		global $wpdb;
+		$wpdb = $this->original_wpdb;
+
+		$GLOBALS['_wp_filter_callbacks']['wpdo_register_entity_fields'] = $this->saved_field_listeners;
+	}
+
+	private function make_job(): array {
+		return array(
+			'job_id'           => 'test-job',
+			'log'              => array(),
+			'state'            => 'running',
+			'overall_progress' => 0,
+			'metrics'          => array(
+				'ratio_start' => 1.5,
+				'ratio_now'   => 1.5,
+			),
+			'options'          => array(),
+		);
+	}
+
+	// ── WPDO_Phase_Diagnose ───────────────────────────────────────────────────
+
+	public function test_diagnose_name(): void {
+		$phase = new WPDO_Phase_Diagnose( 'user' );
+		$this->assertSame( 'diagnose', $phase->name() );
+	}
+
+	public function test_diagnose_returns_ok(): void {
+		$phase  = new WPDO_Phase_Diagnose( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+		$this->assertSame( 'ok', $result['status'] );
+	}
+
+	public function test_diagnose_records_eav_rows_in_metrics(): void {
+		// With $wpdb returning null, count_eav_residue() → 0. Key must exist.
+		$phase = new WPDO_Phase_Diagnose( 'user' );
+		$job   = $this->make_job();
+		$phase->execute( $job );
+		$this->assertArrayHasKey( 'eav_rows_now', $job['metrics'] );
+		$this->assertIsInt( $job['metrics']['eav_rows_now'] );
+	}
+
+	public function test_diagnose_records_ratio_in_metrics(): void {
+		// 0 users → ratio = 0. Key must exist.
+		$phase = new WPDO_Phase_Diagnose( 'user' );
+		$job   = $this->make_job();
+		$phase->execute( $job );
+		$this->assertArrayHasKey( 'ratio_now', $job['metrics'] );
+	}
+
+	public function test_diagnose_appends_log_entry(): void {
+		$phase = new WPDO_Phase_Diagnose( 'user' );
+		$job   = $this->make_job();
+		$phase->execute( $job );
+		$this->assertNotEmpty( $job['log'] );
+		$this->assertStringContainsString( 'Diagnose', $job['log'][0] );
+	}
+
+	// ── WPDO_Phase_Install_Schema ─────────────────────────────────────────────
+
+	public function test_install_schema_name(): void {
+		$phase = new WPDO_Phase_Install_Schema( 'user' );
+		$this->assertSame( 'install_schema', $phase->name() );
+	}
+
+	public function test_install_schema_succeeds_when_no_groups_registered(): void {
+		// No groups registered for 'user' in unit-test bootstrap → $missing stays empty.
+		$phase  = new WPDO_Phase_Install_Schema( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+		$this->assertSame( 'ok', $result['status'] );
+	}
+
+	public function test_install_schema_appends_log_entry(): void {
+		$phase = new WPDO_Phase_Install_Schema( 'user' );
+		$job   = $this->make_job();
+		$phase->execute( $job );
+		$this->assertNotEmpty( $job['log'] );
+		$this->assertStringContainsString( 'Schema migration ok', $job['log'][0] );
+	}
+
+	// ── WPDO_Phase_Backfill_Bulk ──────────────────────────────────────────────
+
+	public function test_backfill_bulk_name(): void {
+		$phase = new WPDO_Phase_Backfill_Bulk( 'user' );
+		$this->assertSame( 'backfill_bulk', $phase->name() );
+	}
+
+	public function test_backfill_bulk_skips_on_dry_run(): void {
+		$phase  = new WPDO_Phase_Backfill_Bulk( 'user' );
+		$job    = array_merge( $this->make_job(), array( 'options' => array( 'dry_run' => true ) ) );
+		$result = $phase->execute( $job );
+		$this->assertSame( 'ok', $result['status'] );
+		$this->assertStringContainsString( 'dry_run', $job['log'][0] ?? '' );
+	}
+
+	public function test_backfill_bulk_returns_ok_with_no_groups(): void {
+		// No groups → loop body never executes → 0 groups, 0 rows.
+		$phase  = new WPDO_Phase_Backfill_Bulk( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+		$this->assertSame( 'ok', $result['status'] );
+		$found_summary = false;
+		foreach ( $job['log'] as $line ) {
+			if ( str_contains( $line, 'Bulk backfill' ) ) {
+				$found_summary = true;
+				$this->assertStringContainsString( '0 groups', $line );
+				break;
+			}
+		}
+		$this->assertTrue( $found_summary, 'Log must contain Bulk backfill summary.' );
+	}
+
+	// ── WPDO_Phase_Backfill_Unserialize ───────────────────────────────────────
+
+	public function test_backfill_unserialize_name(): void {
+		$phase = new WPDO_Phase_Backfill_Unserialize( 'user' );
+		$this->assertSame( 'backfill_unserialize', $phase->name() );
+	}
+
+	public function test_backfill_unserialize_skips_on_dry_run(): void {
+		$phase  = new WPDO_Phase_Backfill_Unserialize( 'user' );
+		$job    = array_merge( $this->make_job(), array( 'options' => array( 'dry_run' => true ) ) );
+		$result = $phase->execute( $job );
+		$this->assertSame( 'ok', $result['status'] );
+		$this->assertStringContainsString( 'dry_run', $job['log'][0] ?? '' );
+	}
+
+	public function test_backfill_unserialize_returns_ok_with_no_json_groups(): void {
+		// No groups with JSON fields → loop body never executes.
+		$phase  = new WPDO_Phase_Backfill_Unserialize( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+		$this->assertSame( 'ok', $result['status'] );
+	}
+
+	public function test_backfill_unserialize_appends_total_log_entry(): void {
+		$phase = new WPDO_Phase_Backfill_Unserialize( 'user' );
+		$job   = $this->make_job();
+		$phase->execute( $job );
+		$this->assertNotEmpty( $job['log'] );
+		$last = end( $job['log'] );
+		$this->assertStringContainsString( 'Row-by-row backfill', $last );
+	}
+
+	// ── WPDO_Phase_Verify_Sample ──────────────────────────────────────────────
+
+	public function test_verify_sample_name(): void {
+		$phase = new WPDO_Phase_Verify_Sample( 'user' );
+		$this->assertSame( 'verify_sample', $phase->name() );
+	}
+
+	public function test_verify_sample_24h_starts_window_when_no_started_at(): void {
+		$phase  = new WPDO_Phase_Verify_Sample( 'user' );
+		$job    = array_merge( $this->make_job(), array( 'options' => array( 'verify_24h' => true ) ) );
+		$result = $phase->execute( $job );
+		$this->assertSame( 'in_progress', $result['status'] );
+		$this->assertArrayHasKey( 'phase_started_at', $job );
+	}
+
+	public function test_verify_sample_24h_stays_in_progress_during_window(): void {
+		$phase = new WPDO_Phase_Verify_Sample( 'user' );
+		$job   = array_merge(
+			$this->make_job(),
+			array(
+				'options'          => array( 'verify_24h' => true ),
+				'phase_started_at' => time() - 3600, // 1 hour ago — still within 24h window
+			)
+		);
+		$result = $phase->execute( $job );
+		$this->assertSame( 'in_progress', $result['status'] );
+	}
+
+	public function test_verify_sample_succeeds_with_zero_users(): void {
+		// $wpdb->get_var() returns null → 0 users → 0 samples → 0 diffs → ok.
+		$phase  = new WPDO_Phase_Verify_Sample( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+		$this->assertSame( 'ok', $result['status'] );
+	}
+
+	public function test_verify_sample_log_contains_compare_summary(): void {
+		$phase = new WPDO_Phase_Verify_Sample( 'user' );
+		$job   = $this->make_job();
+		$phase->execute( $job );
+		$found = false;
+		foreach ( $job['log'] as $line ) {
+			if ( str_contains( $line, 'Verify' ) ) {
+				$found = true;
+				break;
+			}
+		}
+		$this->assertTrue( $found, 'Log must contain Verify summary.' );
+	}
+
+	public function test_verify_sample_constants(): void {
+		$this->assertSame( 500, WPDO_Phase_Verify_Sample::VERIFY_SAMPLE_MIN );
+		$this->assertEqualsWithDelta( 0.10, WPDO_Phase_Verify_Sample::VERIFY_SAMPLE_RATIO, 0.0001 );
+	}
+}

tests/unit/MigrationPhaseTest.php

@@ -0,0 +1,272 @@
+<?php
+declare(strict_types=1);
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Unit tests for WPDO_Migration_Phase_Base and WPDO_Phase_Completed.
+ *
+ * WPDO_Phase_Completed is the simplest phase — no external class calls — so it
+ * exercises the full interface contract without mocking infrastructure.
+ */
+class MigrationPhaseTest extends TestCase {
+
+	private function make_job( float $ratio_start = 1.5, float $ratio_now = 0.8 ): array {
+		return array(
+			'job_id'           => 'test-job',
+			'log'              => array(),
+			'state'            => 'running',
+			'overall_progress' => 0,
+			'metrics'          => array(
+				'ratio_start' => $ratio_start,
+				'ratio_now'   => $ratio_now,
+			),
+		);
+	}
+
+	// ── WPDO_Phase_Completed ──────────────────────────────────────────────────
+
+	public function test_completed_returns_done_status(): void {
+		$phase  = new WPDO_Phase_Completed( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+
+		$this->assertSame( 'done', $result['status'] );
+	}
+
+	public function test_completed_sets_state_to_completed(): void {
+		$phase = new WPDO_Phase_Completed( 'user' );
+		$job   = $this->make_job();
+		$phase->execute( $job );
+
+		$this->assertSame( 'completed', $job['state'] );
+	}
+
+	public function test_completed_sets_overall_progress_to_100(): void {
+		$phase = new WPDO_Phase_Completed( 'user' );
+		$job   = $this->make_job();
+		$phase->execute( $job );
+
+		$this->assertSame( 100, $job['overall_progress'] );
+	}
+
+	public function test_completed_sets_completed_at_timestamp(): void {
+		$before = time();
+		$phase  = new WPDO_Phase_Completed( 'user' );
+		$job    = $this->make_job();
+		$phase->execute( $job );
+
+		$this->assertGreaterThanOrEqual( $before, $job['completed_at'] );
+		$this->assertLessThanOrEqual( time(), $job['completed_at'] );
+	}
+
+	public function test_completed_appends_log_entry(): void {
+		$phase = new WPDO_Phase_Completed( 'user' );
+		$job   = $this->make_job( 1.5, 0.75 );
+		$phase->execute( $job );
+
+		$this->assertNotEmpty( $job['log'] );
+		$last_line = end( $job['log'] );
+		$this->assertStringContainsString( 'Migration complete', $last_line );
+	}
+
+	public function test_completed_name_is_completed(): void {
+		$phase = new WPDO_Phase_Completed( 'user' );
+		$this->assertSame( 'completed', $phase->name() );
+	}
+
+	// ── WPDO_Migration_Phase_Base log truncation ──────────────────────────────
+
+	public function test_log_truncates_at_max_log_lines(): void {
+		$phase = new WPDO_Phase_Completed( 'user' );
+		$job   = $this->make_job();
+
+		// Each execute() appends exactly one log entry — call it MAX+5 times.
+		$max = WPDO_Migration_Phase_Base::MAX_LOG_LINES;
+		for ( $i = 0; $i < $max + 5; $i++ ) {
+			$phase->execute( $job );
+		}
+
+		$this->assertCount( $max, $job['log'] );
+	}
+
+	public function test_log_keeps_most_recent_lines_when_truncating(): void {
+		$phase = new WPDO_Phase_Completed( 'user' );
+		$job   = $this->make_job();
+
+		$max = WPDO_Migration_Phase_Base::MAX_LOG_LINES;
+		for ( $i = 0; $i < $max + 10; $i++ ) {
+			$phase->execute( $job );
+		}
+
+		// Log contains exactly MAX lines with truncation keeping the most recent.
+		$this->assertCount( $max, $job['log'] );
+		// First kept line was written after at least 10 entries were discarded.
+		$first_line = $job['log'][0];
+		$this->assertStringContainsString( 'Migration complete', $first_line );
+	}
+
+	// ── Phase interface contract ───────────────────────────────────────────────
+
+	public function test_phase_implements_interface(): void {
+		$phase = new WPDO_Phase_Completed( 'user' );
+		// Interfaces cannot be class_alias()'d; the phase contract is core-internal
+		// (only the 11 built-in phases implement it), so assert the canonical name.
+		$this->assertInstanceOf( TMDO_Migration_Phase_Interface::class, $phase );
+	}
+
+	public function test_phase_entity_type_injectable(): void {
+		$phase_user = new WPDO_Phase_Completed( 'user' );
+		$phase_term = new WPDO_Phase_Completed( 'term' );
+
+		// Both are independent instances — no shared state.
+		$job_a = $this->make_job();
+		$job_b = $this->make_job();
+		$phase_user->execute( $job_a );
+		$phase_term->execute( $job_b );
+
+		$this->assertSame( 'completed', $job_a['state'] );
+		$this->assertSame( 'completed', $job_b['state'] );
+	}
+
+	// ── Phase_Cleanup — RuntimeException guards (P1-11, highest priority) ────────
+
+	protected function setUp(): void {
+		$GLOBALS['_wp_options'] = [];
+		WPDO_Mode_Manager::reset_cache();
+	}
+
+	private function make_mode_option( string $entity_type, string $mode ): void {
+		$GLOBALS['_wp_options']['wpdo_bridge_modes'] = array( $entity_type => $mode );
+		WPDO_Mode_Manager::reset_cache();
+	}
+
+	public function test_cleanup_throws_when_mode_not_aeav_only(): void {
+		$this->make_mode_option( 'user', 'dual_write' );
+		$phase = new WPDO_Phase_Cleanup( 'user' );
+		$job   = $this->make_job();
+
+		$this->expectException( \RuntimeException::class );
+		$this->expectExceptionMessageMatches( '/must be aeav_only/' );
+		$phase->execute( $job );
+	}
+
+	public function test_cleanup_throws_when_auto_backup_requested_but_no_path(): void {
+		$this->make_mode_option( 'user', 'aeav_only' );
+		$phase = new WPDO_Phase_Cleanup( 'user' );
+		$job   = array_merge(
+			$this->make_job(),
+			array(
+				'options'     => array( 'auto_backup' => true ),
+				'backup_path' => '', // empty — simulates backup that never ran
+			)
+		);
+
+		$this->expectException( \RuntimeException::class );
+		$this->expectExceptionMessageMatches( '/no backup_path on record/' );
+		$phase->execute( $job );
+	}
+
+	public function test_cleanup_skips_when_dry_run(): void {
+		$this->make_mode_option( 'user', 'dual_write' ); // wrong mode, but dry_run should short-circuit first
+		$phase = new WPDO_Phase_Cleanup( 'user' );
+		$job   = array_merge( $this->make_job(), array( 'options' => array( 'dry_run' => true ) ) );
+
+		$result = $phase->execute( $job );
+		$this->assertSame( 'ok', $result['status'] );
+		$this->assertStringContainsString( 'dry_run', $job['log'][0] ?? '' );
+	}
+
+	// ── Phase_Demote ──────────────────────────────────────────────────────────────
+
+	public function test_demote_skips_when_not_aeav_only(): void {
+		$this->make_mode_option( 'user', 'shadow_read' );
+		$phase  = new WPDO_Phase_Demote( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+
+		$this->assertSame( 'ok', $result['status'] );
+		$this->assertStringContainsString( 'skipped', $job['log'][0] ?? '' );
+	}
+
+	public function test_demote_transitions_aeav_only_to_dual_write(): void {
+		$this->make_mode_option( 'user', 'aeav_only' );
+		$phase  = new WPDO_Phase_Demote( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+
+		$this->assertSame( 'ok', $result['status'] );
+		$this->assertSame( 'dual_write', WPDO_Mode_Manager::get( 'user' ) );
+	}
+
+	// ── Phase_Backup — skip when auto_backup=false ────────────────────────────────
+
+	public function test_backup_skips_when_auto_backup_false(): void {
+		$phase = new WPDO_Phase_Backup( 'user' );
+		$job   = array_merge( $this->make_job(), array( 'options' => array( 'auto_backup' => false ) ) );
+
+		$result = $phase->execute( $job );
+		$this->assertSame( 'ok', $result['status'] );
+		$this->assertStringContainsString( 'skipped', $job['log'][0] ?? '' );
+	}
+
+	// ── Phase_Promote_Aeav ────────────────────────────────────────────────────────
+
+	public function test_promote_aeav_skips_when_already_aeav_only(): void {
+		$this->make_mode_option( 'user', 'aeav_only' );
+		$phase  = new WPDO_Phase_Promote_Aeav( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+
+		$this->assertSame( 'ok', $result['status'] );
+		$this->assertStringContainsString( 'Already', $job['log'][0] ?? '' );
+	}
+
+	public function test_promote_aeav_transitions_from_shadow_read(): void {
+		$this->make_mode_option( 'user', 'shadow_read' );
+		$phase  = new WPDO_Phase_Promote_Aeav( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+
+		$this->assertSame( 'ok', $result['status'] );
+		$this->assertSame( 'aeav_only', WPDO_Mode_Manager::get( 'user' ) );
+	}
+
+	// ── Phase_Promote_Shadow ──────────────────────────────────────────────────────
+
+	public function test_promote_shadow_transitions_from_dual_write(): void {
+		$this->make_mode_option( 'user', 'dual_write' );
+		$phase  = new WPDO_Phase_Promote_Shadow( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+
+		$this->assertSame( 'ok', $result['status'] );
+		$this->assertSame( 'shadow_read', WPDO_Mode_Manager::get( 'user' ) );
+	}
+
+	public function test_promote_shadow_skips_when_already_at_shadow_or_higher(): void {
+		$this->make_mode_option( 'user', 'aeav_only' );
+		$phase  = new WPDO_Phase_Promote_Shadow( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+
+		$this->assertSame( 'ok', $result['status'] );
+		// Mode should be unchanged (already past shadow_read).
+		$this->assertSame( 'aeav_only', WPDO_Mode_Manager::get( 'user' ) );
+	}
+
+	// ── Phase name() contract ─────────────────────────────────────────────────────
+
+	public function test_all_phases_return_expected_names(): void {
+		$cases = array(
+			array( new WPDO_Phase_Backup( 'user' ), 'backup' ),
+			array( new WPDO_Phase_Cleanup( 'user' ), 'cleanup' ),
+			array( new WPDO_Phase_Demote( 'user' ), 'demote' ),
+			array( new WPDO_Phase_Promote_Aeav( 'user' ), 'promote_aeav' ),
+			array( new WPDO_Phase_Promote_Shadow( 'user' ), 'promote_shadow' ),
+		);
+		foreach ( $cases as [ $phase, $expected ] ) {
+			$this->assertSame( $expected, $phase->name() );
+		}
+	}
+}