From 758f86c11c67d566ac3b606d50f83926b462081b Mon Sep 17 00:00:00 2001
From: Simone <simone.chifari@gmail.com>
Date: Sat, 23 May 2026 21:56:59 +0200
Subject: [PATCH] docs(lifecycle): add CI/CD job lifecycle documentation with
 flowchart and phase breakdown

---
 docs/LIFECYCLE.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 docs/LIFECYCLE.md

diff --git a/docs/LIFECYCLE.md b/docs/LIFECYCLE.md
new file mode 100644
index 0000000..8c6d07d
--- /dev/null
+++ b/docs/LIFECYCLE.md
@@ -0,0 +1,78 @@
+# CI/CD Job Lifecycle
+
+```mermaid
+flowchart TD
+    A([git push]) --> B[Gitea Actions\ntrigger workflow]
+    B --> C[act_runner\nWindows service]
+    C --> D["python -m ci_orchestrator job\njob.py · job()"]
+
+    D --> SRC{use-git-clone?}
+
+    SRC -->|false — default| HOST_CLONE["host: git clone\n+ Compress-Archive\n+ WinRM copy zip\n+ Expand-Archive in VM"]
+    SRC -->|true — opt-in| VM_CLONE["skip host clone\nVM: git clone --recurse-submodules\nhttps://PAT@gitea/repo\n~25.7% faster"]
+
+    HOST_CLONE --> E
+    VM_CLONE --> E
+
+    D --> LB
+    LB --> E
+
+    E["vm_new()\nlinked clone from template snapshot"]
+    E --> F{guestOS in VMX?}
+
+    F -->|ubuntu-*| G_WAIT["wait_ready()\nSSH poll · port 22"]
+    F -->|Windows| W_WAIT["wait_ready()\nWinRM poll · port 5986"]
+
+    G_WAIT --> G_PROBE["_probe_transport()\nSshTransport"]
+    W_WAIT --> W_PROBE["_probe_transport()\nWinRmTransport"]
+
+    G_PROBE --> G_BUILD["_linux_build()\nSSH + SFTP · paramiko"]
+    W_PROBE --> W_BUILD["_windows_build()\nWinRM · pypsrp"]
+
+    G_BUILD --> G_ART["_linux_collect()\nSCP artifacts"]
+    W_BUILD --> W_ART["_windows_collect()\nWinRM Copy-Item"]
+
+    G_ART --> DESTROY
+    W_ART --> DESTROY
+
+    DESTROY["_destroy_clone()\nvmrun stop + deleteVM"]
+    DESTROY --> DONE([Job complete])
+
+    subgraph Templates
+        T1["WinBuild2025\nBaseClean · WinRM"]
+        T2["WinBuild2022\nBaseClean · WinRM"]
+        T3["LinuxBuild2404\nBaseClean-Linux · SSH"]
+    end
+
+    E -.->|clone from| T1
+    E -.->|clone from| T2
+    E -.->|clone from| T3
+
+    subgraph Backend
+        LB["load_backend()\nWorkstationVmrunBackend\nwraps vmrun.exe"]
+    end
+```
+
+## Phase breakdown
+
+| Phase | Module | Transport |
+|-------|--------|-----------|
+| Clone VM | `commands/vm.py · vm_new()` | `vmrun.exe` (host) |
+| Source delivery | workflow input `use-git-clone` | WinRM (in-VM git clone) or host zip |
+| Wait ready | `commands/wait.py · wait_ready()` | SSH/22 or WinRM/5986 |
+| Build | `commands/build.py · build_run()` | `paramiko` (Linux) / `pypsrp` (Windows) |
+| Collect artifacts | `commands/artifacts.py · artifacts_collect()` | SCP (Linux) / WinRM Copy-Item (Windows) |
+| Destroy VM | `commands/job.py · _destroy_clone()` | `vmrun.exe` (host) |
+
+## Transport selection
+
+`job.py` reads `guestOS` from the cloned `.vmx`:
+- `ubuntu-*` → `SshTransport` (paramiko, key auth, `ci_build` user)
+- anything else → `WinRmTransport` (pypsrp, HTTPS/5986)
+
+## Source delivery modes
+
+| Mode | Trigger | Flow | Notes |
+|------|---------|------|-------|
+| Standard | `use-git-clone: false` (default) | host clone → zip → WinRM copy → expand | No credentials in VM |
+| UseGitClone | `use-git-clone: true` | VM clones directly via PAT | 25.7% faster, PAT never persisted |