feat(validate): add migration validation role

.github/workflows/pre-commit.yml

@@ -78,6 +78,14 @@ jobs:
         run: |
           pip install -r requirements-ci.txt
 
+      - name: Install collections for the VMware module-contract guard
+        # The validate_migration-vmware-contract hook verifies the REAL installed
+        # module contracts (vmware.vmware.vm_powerstate and
+        # community.vmware.vmware_guest_info); .ansible/ is gitignored, so
+        # CI must install them or the guard fails closed on every PR.
+        run: |
+          ansible-galaxy collection install vmware.vmware community.vmware
+
       - name: Cache pre-commit environments
         uses: actions/cache@v4
         with:

.pre-commit-config.yaml

@@ -53,6 +53,20 @@ repos:
   # Ensures generated documentation (README.md and role READMEs) are up-to-date
   - repo: local
     hooks:
+      - id: validate_migration-vmware-contract
+        name: Verify installed VMware power-state module contract
+        entry: python3 scripts/check-validate-migration-vmware.py
+        language: system
+        pass_filenames: false
+        files: ^(roles/validate_migration/|galaxy.yml|requirements-dev.yml|scripts/check-validate-migration-vmware.py)
+
+      - id: validate_migration-power-offline
+        name: Test validate_migration power-off with offline module doubles
+        entry: python3 -m unittest discover --start-directory tests/unit --pattern test_validate_migration_power.py
+        language: system
+        pass_filenames: false
+        files: ^(roles/validate_migration/|tests/unit/test_validate_migration_power.py)
+
       - id: update-documentation
         name: Generate documentation
         entry: bash scripts/update-documentation.sh

README.md

@@ -55,6 +55,7 @@ This collection includes the following roles for managing OpenShift Virtualizati
 * [utility_aap_deploy](roles/utility_aap_deploy/README.md) - Deploys an instance of Ansible Automation Platform.
 * [utility_openshift_target_credential](roles/utility_openshift_target_credential/README.md) - A utility role to manage OpenShift target cluster credentials for migration
 * [utility_registry_credentials](roles/utility_registry_credentials/README.md) - Manages registry credentials in an OpenShift namespace.
+* [validate_migration](roles/validate_migration/README.md) - Validate migration outcomes after vmf_migrate completes — Migration status, migrated VM presence and state, target list match, guest agent, IP addresses, disk topology, and the fail-closed source power-off.
 <!--ROLES_LIST_END-->
 
 ## Requirements

changelogs/fragments/108-validate-migration-role.yml

@@ -0,0 +1,4 @@
+---
+minor_changes:
+  - Add validate_migration role to validate migration outcomes after vmf_migrate completes — migration status, migrated VM presence and running state, target list match, guest agent, IP addresses, disk topology, and the per-VM fail-closed source power-off (see docs/adr/0001-validate-migration-fail-closed-power-off.md; playbook vmf_validate_migration.yml).
+...

docs/adr/0001-validate-migration-fail-closed-power-off.md

@@ -0,0 +1,38 @@
+# ADR-0001: Migration validation source power-off is per-VM and fail-closed
+
+Date: 2026-10-16
+Status: Accepted
+
+## Context
+
+Migration validation (the post-migration validation pass) powers off source VMs by
+default after a migration. A power-off is destructive: if the migration
+failed or a migrated VM is unhealthy, powering off its source removes the
+operator's fallback.
+
+## Decision
+
+The source power-off is per-VM and fail-closed:
+
+- A source VM is powered off only after ITS migrated counterpart passes
+  every validate_migration check.
+- A failed check leaves that source VM running; the role reports which
+  sources stayed on and why.
+- The toggle (`validate_migration_power_off_source`, default on) switches the
+  action off entirely; in that mode the role reports source power state as
+  a read-only check and never mutates.
+
+The power-off is a hard stop via the vCenter API — not a graceful guest
+shutdown; the migrated counterpart is already validated at that point. It
+is the only sanctioned mutation in validate_migration; every other check is a
+read-only probe.
+
+## Consequences
+
+- Partial migrations are safe: the sources of failed VMs stay available
+  for retry or rollback.
+- The default-on toggle is safe only because of the fail-closed gate —
+  the two decisions are paired and must not be separated.
+- Operators running with the toggle on must treat a "sources still
+  running" summary as the signal to investigate, not as a role failure to
+  force through.

galaxy.yml

@@ -26,6 +26,7 @@ dependencies:
   "redhat.openshift_virtualization": ">=2.1.0"
   "redhat.openshift": ">=4.0.0"
   "vmware.vmware_rest": ">=4.6.0"
+  "vmware.vmware": ">=1.11.0"
   # AAP 2.5 can leverage the latest version of the collection. 2.4 must use <=4.5.12
   "ansible.controller": "*"
   "ansible.posix": ">=1.6.2"