refactor: restructure implementation plan for clarity and readability

plans/implementation-plan-A-B.md

@@ -8,11 +8,21 @@ mantenendo VMware Workstation Pro come hypervisor (Fase B). Il risultato
 è un unico stack Python in produzione su Linux, con i template VM, i
 workflow Gitea Actions e act_runner invariati nella sostanza.
 
-| Fase | Obiettivo | Output verificabile | Stato |
+Sintesi fasi:
-| ---- | --------- | ------------------- | ----- |
+
-| A | Rewrite Python dell'orchestratore (host Windows attuale) | `python -m ci_orchestrator job ...` sostituisce `Invoke-CIJob.ps1`; `pytest` ≥70% coverage; workflow `build-nsInnoUnp.yml` PASS | da iniziare |
+- **Fase A — Rewrite Python dell'orchestratore (host Windows attuale)**
-| B | Migrazione host a Linux Mint + Workstation Pro Linux | act_runner come `act-runner.service` systemd; storage `/var/lib/ci/`; burn-in 4 job concorrenti PASS | da iniziare (gating: A done) |
+  - Output verificabile: `python -m ci_orchestrator job ...` sostituisce
-| C | (Hook only, non implementata) backend ESXi via `pyVmomi` | Protocol `VmBackend` rispettato; `[backend]` selector in `config.toml` | non in scope |
+    `Invoke-CIJob.ps1`; `pytest` ≥70% coverage; workflow
+    `build-nsInnoUnp.yml` PASS.
+  - Stato: da iniziare.
+- **Fase B — Migrazione host a Linux Mint + Workstation Pro Linux**
+  - Output verificabile: act_runner come `act-runner.service` systemd;
+    storage `/var/lib/ci/`; burn-in 4 job concorrenti PASS.
+  - Stato: da iniziare (gating: A done).
+- **Fase C — (Hook only, non implementata) backend ESXi via `pyVmomi`**
+  - Output verificabile: Protocol `VmBackend` rispettato; `[backend]`
+    selector in `config.toml`.
+  - Stato: non in scope.
 
 Decisioni architetturali già prese e non rinegoziabili:
 
@@ -875,28 +885,98 @@ flowchart TD
 
 ## 6. Matrice rischi consolidata
 
-| Rischio | Fase | Severità | Mitigazione | Owner action item |
+Ogni voce: **Rischio** — Fase / Severità / Mitigazione / Owner action item.
-| ------- | ---- | -------- | ----------- | ----------------- |
+
-| `pypsrp` edge case con WinRM HTTPS self-signed | A1 | Media | PoC `wait-ready` come primo deliverable A1 prima di committare al resto | A1 attività #10 |
+- **`pypsrp` edge case con WinRM HTTPS self-signed**
-| `keyring` sotto SYSTEM (act_runner service) non vede credenziali utente | A1, B3 | Alta | DPAPI machine scope su Win; PoC vault file `age`/`sops` su Linux in B3 | X3 attività complete |
+  - Fase: A1 — Severità: Media
-| Perdita di know-how errori `AGENTS.md` #9–#12 durante refactor | A5 | Media | Ognuno convertito in test pytest **prima** di rimuovere il `.ps1` corrispondente | A5 attività #1 |
+  - Mitigazione: PoC `wait-ready` come primo deliverable A1 prima di
-| Doppio mantenimento PS+Python durante migrazione | A2–A4 | Alta | Strategia shim minimizza la finestra; `lint.yml` dual-stack | X1 attività complete |
+    committare al resto.
-| Astrazione `VmBackend` over-engineered se Fase C non parte mai | A1 | Bassa | 1 implementazione concreta + Protocol = ~50 LOC extra; costo trascurabile | accettato |
+  - Owner: A1 attività #10.
-| act_runner cattura male output Python (encoding cp1252) | A4 | Media | `PYTHONIOENCODING=utf-8` in `runner/config.yaml` | A4 attività #4 |
+- **`keyring` sotto SYSTEM (act_runner service) non vede credenziali utente**
-| `vmrun` su Linux ha differenze parsing output `list` / `getGuestIPAddress` | B1 | Media | Test modulo `vmrun.py` su Linux subito in B1 | B1 attività #3 |
+  - Fase: A1, B3 — Severità: Alta
-| Performance I/O linked clone su ext4 vs NTFS | B7 | Bassa | Misurare con burn-in B7; eventualmente XFS/BTRFS | B7 attività #5 |
+  - Mitigazione: DPAPI machine scope su Win; PoC vault file `age`/`sops`
-| `vmnet8` NAT range diverso → IP collision LAN | B1 | Media | Allineare `192.168.79.0/24` in B1 | B1 attività #5 |
+    su Linux in B3.
-| WinRM HTTPS da Linux: TLS 1.2 cipher non supportati dal Windows guest | B2 | Media | Smoke test prima del cutover; stesso codice già testato in A1 da Win host | B2 attività #7 |
+  - Owner: X3 attività complete.
-| Permessi `/var/lib/ci/build-vms/` per `ci-runner` | B1 | Media | ACL POSIX con `setfacl -d -m` | B1 attività #8 |
+- **Perdita di know-how errori `AGENTS.md` #9–#12 durante refactor**
-| `secret-tool` headless senza D-Bus session | B3 | Alta | PoC + fallback file vault `age` | B3 attività #5 |
+  - Fase: A5 — Severità: Media
-| Errore `AGENTS.md` #11 (machine-id Linux) si ripropone | B2 | Bassa | Già documentato; fix nel template prima dello snapshot | preservato |
+  - Mitigazione: ognuno convertito in test pytest **prima** di rimuovere
-| Errore `AGENTS.md` #12 (stderr nativa + `'Stop'`) | A | N/A | Sparisce in Python | dichiarato in A5 |
+    il `.ps1` corrispondente.
-| Cutover gap window (job in errore tra stop Win e start Linux) | B6 | Media | Finestra a zero traffic + Gitea "paused" preventivo | B6 attività #2 |
+  - Owner: A5 attività #1.
-| Decommissioning prematuro elimina rollback | B8 | Media | Gating ≥1 settimana + ≥1 mese spento prima di riallocare | B8 attività #3 |
+- **Doppio mantenimento PS+Python durante migrazione**
-| **(integrazione A↔B)** Shim PS che assume path Windows si rompe in Fase B | A2, B6 | Media | Shim deve invocare Python via path da env (`%CI_PYTHON_VENV%`), non hardcoded `F:\` | A2 attività #7 |
+  - Fase: A2–A4 — Severità: Alta
-| **(integrazione A↔B)** `config.toml` con default Win-only blocca B1 | A1, B1 | Bassa | A1 deve già includere `[paths.linux]` con default POSIX | A1 attività #4 |
+  - Mitigazione: strategia shim minimizza la finestra; `lint.yml`
-| **(integrazione A↔B)** Test pytest assumono `Path('F:\\CI')` e falliscono su Linux | A1, B1 | Media | Fixture parametrizzata `tmp_path` in tutti i test, no path hardcoded | A1 attività #11 |
+    dual-stack.
-| Licenza Workstation Pro Linux cambia post-Broadcom | B1 | Bassa | Free per uso personale e commerciale dal 2024; monitorare; piano B = KVM (rimandato) | B1 monitoring continuo |
+  - Owner: X1 attività complete.
+- **Astrazione `VmBackend` over-engineered se Fase C non parte mai**
+  - Fase: A1 — Severità: Bassa
+  - Mitigazione: 1 implementazione concreta + Protocol = ~50 LOC extra;
+    costo trascurabile.
+  - Owner: accettato.
+- **act_runner cattura male output Python (encoding cp1252)**
+  - Fase: A4 — Severità: Media
+  - Mitigazione: `PYTHONIOENCODING=utf-8` in `runner/config.yaml`.
+  - Owner: A4 attività #4.
+- **`vmrun` su Linux ha differenze parsing output `list` / `getGuestIPAddress`**
+  - Fase: B1 — Severità: Media
+  - Mitigazione: test modulo `vmrun.py` su Linux subito in B1.
+  - Owner: B1 attività #3.
+- **Performance I/O linked clone su ext4 vs NTFS**
+  - Fase: B7 — Severità: Bassa
+  - Mitigazione: misurare con burn-in B7; eventualmente XFS/BTRFS.
+  - Owner: B7 attività #5.
+- **`vmnet8` NAT range diverso → IP collision LAN**
+  - Fase: B1 — Severità: Media
+  - Mitigazione: allineare `192.168.79.0/24` in B1.
+  - Owner: B1 attività #5.
+- **WinRM HTTPS da Linux: TLS 1.2 cipher non supportati dal Windows guest**
+  - Fase: B2 — Severità: Media
+  - Mitigazione: smoke test prima del cutover; stesso codice già testato
+    in A1 da Win host.
+  - Owner: B2 attività #7.
+- **Permessi `/var/lib/ci/build-vms/` per `ci-runner`**
+  - Fase: B1 — Severità: Media
+  - Mitigazione: ACL POSIX con `setfacl -d -m`.
+  - Owner: B1 attività #8.
+- **`secret-tool` headless senza D-Bus session**
+  - Fase: B3 — Severità: Alta
+  - Mitigazione: PoC + fallback file vault `age`.
+  - Owner: B3 attività #5.
+- **Errore `AGENTS.md` #11 (machine-id Linux) si ripropone**
+  - Fase: B2 — Severità: Bassa
+  - Mitigazione: già documentato; fix nel template prima dello snapshot.
+  - Owner: preservato.
+- **Errore `AGENTS.md` #12 (stderr nativa + `'Stop'`)**
+  - Fase: A — Severità: N/A
+  - Mitigazione: sparisce in Python.
+  - Owner: dichiarato in A5.
+- **Cutover gap window (job in errore tra stop Win e start Linux)**
+  - Fase: B6 — Severità: Media
+  - Mitigazione: finestra a zero traffic + Gitea "paused" preventivo.
+  - Owner: B6 attività #2.
+- **Decommissioning prematuro elimina rollback**
+  - Fase: B8 — Severità: Media
+  - Mitigazione: gating ≥1 settimana + ≥1 mese spento prima di
+    riallocare.
+  - Owner: B8 attività #3.
+- **(integrazione A↔B) Shim PS che assume path Windows si rompe in Fase B**
+  - Fase: A2, B6 — Severità: Media
+  - Mitigazione: shim deve invocare Python via path da env
+    (`%CI_PYTHON_VENV%`), non hardcoded `F:\`.
+  - Owner: A2 attività #7.
+- **(integrazione A↔B) `config.toml` con default Win-only blocca B1**
+  - Fase: A1, B1 — Severità: Bassa
+  - Mitigazione: A1 deve già includere `[paths.linux]` con default POSIX.
+  - Owner: A1 attività #4.
+- **(integrazione A↔B) Test pytest assumono `Path('F:\\CI')` e falliscono su Linux**
+  - Fase: A1, B1 — Severità: Media
+  - Mitigazione: fixture parametrizzata `tmp_path` in tutti i test, no
+    path hardcoded.
+  - Owner: A1 attività #11.
+- **Licenza Workstation Pro Linux cambia post-Broadcom**
+  - Fase: B1 — Severità: Bassa
+  - Mitigazione: free per uso personale e commerciale dal 2024;
+    monitorare; piano B = KVM (rimandato).
+  - Owner: B1 monitoring continuo.
 
 ## 7. Definizione di "fatto" globale (A+B)