document Terraform to Ansible handoff

TODO.md

@@ -162,6 +162,52 @@ still needs a clean kube-proxy-free cluster validation.
   - [ ] Document the required Proxmox storage content types, API permissions,
     SSH access, and node prerequisites.
 
+## Priority 5b: Terraform to Ansible handoff
+
+The Proxmox Terraform path should hand off to the existing Ansible bootstrap
+automatically after the VM is reachable. Terraform owns infrastructure
+creation. Ansible owns host configuration, k3d or K3s bootstrap, ArgoCD
+bootstrap, and verification. GitOps remains the owner of ongoing Kubernetes
+application configuration.
+
+- [ ] Pin and configure the `ansible/ansible` provider.
+  - [ ] Use `ansible_host` with the Terraform-created VM address and the
+    `flatcar_k3d` inventory group.
+  - [ ] Use `ansible_playbook` to run the existing
+    `ansible/bootstrap-flatcar-k3d.yml` playbook after VM creation.
+  - [ ] Add an explicit dependency on the Proxmox VM and its initial network
+    configuration so the playbook cannot start too early.
+  - [ ] Wait for SSH and verify the expected Flatcar user before the main
+    bootstrap tasks run.
+  - [ ] Pass only nonsecret settings through Terraform `extra_vars`, such as
+    the cluster name, repository URL, branch, and feature toggles.
+  - [ ] Keep webhook values, runner tokens, private keys, and Vault passwords
+    out of Terraform configuration, `extra_vars`, and Terraform state.
+  - [ ] Use SSH agent forwarding or a protected key path supplied through the
+    runtime environment rather than committing credentials.
+  - [ ] Prevent every Terraform plan from rerunning the full bootstrap. Use a
+    VM generation, Ignition hash, or explicit bootstrap trigger.
+  - [ ] Make a failed bootstrap easy to retry without recreating the VM.
+  - [ ] Capture useful outputs such as the VM address, Ansible inventory group,
+    kubeconfig artifact path, and verified Kubernetes context.
+
+- [ ] Test the handoff lifecycle.
+  - [ ] Apply from an empty Proxmox project and verify the complete handoff.
+  - [ ] Reapply without changes and verify no unnecessary VM replacement or
+    full Ansible rerun occurs.
+  - [ ] Replace the VM and verify the new Ignition and bootstrap sequence.
+  - [ ] Interrupt Ansible, retry Terraform, and verify safe convergence.
+  - [ ] Destroy the VM and verify that no credentials or stale inventory data
+    remain in the repository.
+
+The provider's [`ansible_host` resource](https://registry.terraform.io/providers/ansible/ansible/latest/docs/resources/host)
+creates inventory hosts from Terraform values. The
+[`ansible_playbook` resource](https://registry.terraform.io/providers/ansible/ansible/latest/docs/resources/playbook)
+then provides the Terraform-to-Ansible execution boundary. This integration
+will be documented as an optional convenience for the Proxmox path, because it
+also means Terraform runs can be longer and Ansible execution metadata may be
+stored in state depending on provider configuration.
+
 ## Priority 6: Documentation and portfolio evidence
 
 - [ ] Update the root README after each automation milestone.