refactor: restructure implementation plan for clarity and readability

2026-05-13 11:08:01 +02:00
parent 770ac1edf8
commit 4ac6dd85f9
1 changed files with 107 additions and 27 deletions
@@ -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 |
-| ---- | --------- | ------------------- | ----- |
-| 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 |
-| 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) |
-| C | (Hook only, non implementata) backend ESXi via `pyVmomi` | Protocol `VmBackend` rispettato; `[backend]` selector in `config.toml` | non in scope |
+Sintesi fasi:
+
+- **Fase A — Rewrite Python dell'orchestratore (host Windows attuale)**
+  - Output verificabile: `python -m ci_orchestrator job ...` sostituisce
+    `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 |
-| ------- | ---- | -------- | ----------- | ----------------- |
-| `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 |
-| `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 |
-| 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 |
-| Doppio mantenimento PS+Python durante migrazione | A2–A4 | Alta | Strategia shim minimizza la finestra; `lint.yml` dual-stack | X1 attività complete |
-| Astrazione `VmBackend` over-engineered se Fase C non parte mai | A1 | Bassa | 1 implementazione concreta + Protocol = ~50 LOC extra; costo trascurabile | accettato |
-| act_runner cattura male output Python (encoding cp1252) | A4 | Media | `PYTHONIOENCODING=utf-8` in `runner/config.yaml` | A4 attività #4 |
-| `vmrun` su Linux ha differenze parsing output `list` / `getGuestIPAddress` | B1 | Media | Test modulo `vmrun.py` su Linux subito in B1 | B1 attività #3 |
-| Performance I/O linked clone su ext4 vs NTFS | B7 | Bassa | Misurare con burn-in B7; eventualmente XFS/BTRFS | B7 attività #5 |
-| `vmnet8` NAT range diverso → IP collision LAN | B1 | Media | Allineare `192.168.79.0/24` in B1 | B1 attività #5 |
-| 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 |
-| Permessi `/var/lib/ci/build-vms/` per `ci-runner` | B1 | Media | ACL POSIX con `setfacl -d -m` | B1 attività #8 |
-| `secret-tool` headless senza D-Bus session | B3 | Alta | PoC + fallback file vault `age` | B3 attività #5 |
-| Errore `AGENTS.md` #11 (machine-id Linux) si ripropone | B2 | Bassa | Già documentato; fix nel template prima dello snapshot | preservato |
-| Errore `AGENTS.md` #12 (stderr nativa + `'Stop'`) | A | N/A | Sparisce in Python | dichiarato in A5 |
-| Cutover gap window (job in errore tra stop Win e start Linux) | B6 | Media | Finestra a zero traffic + Gitea "paused" preventivo | B6 attività #2 |
-| Decommissioning prematuro elimina rollback | B8 | Media | Gating ≥1 settimana + ≥1 mese spento prima di riallocare | B8 attività #3 |
-| **(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 |
-| **(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 |
-| **(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 |
-| 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 |
+Ogni voce: **Rischio** — Fase / Severità / Mitigazione / Owner action item.
+
+- **`pypsrp` edge case con WinRM HTTPS self-signed**
+  - Fase: A1 — Severità: Media
+  - Mitigazione: PoC `wait-ready` come primo deliverable A1 prima di
+    committare al resto.
+  - Owner: A1 attività #10.
+- **`keyring` sotto SYSTEM (act_runner service) non vede credenziali utente**
+  - Fase: A1, B3 — Severità: Alta
+  - Mitigazione: DPAPI machine scope su Win; PoC vault file `age`/`sops`
+    su Linux in B3.
+  - Owner: X3 attività complete.
+- **Perdita di know-how errori `AGENTS.md` #9–#12 durante refactor**
+  - Fase: A5 — Severità: Media
+  - Mitigazione: ognuno convertito in test pytest **prima** di rimuovere
+    il `.ps1` corrispondente.
+  - Owner: A5 attività #1.
+- **Doppio mantenimento PS+Python durante migrazione**
+  - Fase: A2–A4 — Severità: Alta
+  - Mitigazione: strategia shim minimizza la finestra; `lint.yml`
+    dual-stack.
+  - 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)