# Prompt — Generazione piano di implementazione unificato Fase A + Fase B > Copia-incolla il blocco sotto come messaggio iniziale all'IA che dovrà > produrre il piano. L'IA deve avere accesso in lettura al repository > `local-ci-cd-system` (in particolare ai file citati nei riferimenti). --- ## Prompt da fornire all'IA Sei un senior platform/DevOps engineer assegnato al progetto **local-ci-cd-system** (CI/CD on-prem basato su Gitea Actions + act_runner + VMware Workstation Pro + VM ephemere Win/Linux). Il tuo compito è produrre **un singolo documento di piano implementativo dettagliato** che fonde **Fase A** (rewrite Python dell'orchestratore) e **Fase B** (migrazione host da Windows 11 a Linux Mint) in un'unica roadmap eseguibile, mantenendo **hook architetturali compatibili con Fase C** (backend ESXi futuro) senza implementarla. ### Contesto obbligatorio da leggere PRIMA di scrivere Prima di produrre output, leggi e tieni come riferimento: 1. [AGENTS.md](../AGENTS.md) — vincoli host, PowerShell 5.1, errori frequenti (#1–#12). Tutti i punti devono restare validi o essere esplicitamente superati dal piano. 2. [plans/ideas-overview.md](ideas-overview.md) — razionale, ordine, criteri di "fase completata", strategia di rollback. 3. [plans/idea-1-python-rewrite.md](idea-1-python-rewrite.md) — Fase A (decisioni di design, mappa di traduzione, step A1–A5, layout repo, rischi, definizione di fatto). 4. [plans/idea-2-linux-host.md](idea-2-linux-host.md) — Fase B (decisione hypervisor, mappa di adattamento, step B1–B8, rischi, fatto). 5. [plans/idea-3-esxi-support.md](idea-3-esxi-support.md) — Fase C: leggi solo §2 (architettura) e §3 (backend pyVmomi) per sapere quali hook lasciare aperti nel design. 6. [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md), [docs/CI-FLOW.md](../docs/CI-FLOW.md), [docs/HOST-SETUP.md](../docs/HOST-SETUP.md), [docs/RUNBOOK.md](../docs/RUNBOOK.md) per capire layout e operatività attuali. 7. La cartella [scripts/](../scripts/) e [template/](../template/) per conoscere l'inventario reale degli script da portare/tenere. ### Cosa devi produrre Un unico file Markdown chiamato `plans/implementation-plan-A-B.md` con la struttura sotto. Il documento deve essere **autocontenuto** (chi lo legge non deve aprire altri 6 file per capire cosa fare oggi), ma deve **citare** i piani originali quando rimanda a sezioni di dettaglio. ### Struttura obbligatoria del documento Usa esattamente questa scaletta e gli heading indicati: #### `# Piano implementativo unificato — Fase A (Python) + Fase B (host Linux)` #### `## Summary esecutivo` Massimo 25 righe. Includi: - Obiettivo combinato in 2 frasi. - Tabella `Fase | Obiettivo | Output verificabile | Stato`. - Decisioni architetturali chiave già prese (Python 3.11+, pypsrp, paramiko, keyring, Workstation Pro Linux, astrazione `VmBackend`). - Vincoli che NON cambiano (act_runner, Gitea, template VM, workflow YAML invariati a meno di env vars / shell). #### `## Checklist riassuntiva master` Una sola checklist `- [ ]` piatta che enumera **tutti** i deliverable ordinati cronologicamente, con prefisso del macro-step (`[A1]`, `[A2]`, …, `[B1]`, …, `[X]` per gli step trasversali). Deve essere copiabile in un issue tracker. Ogni voce: ≤ 1 riga, verbo all'infinito, deliverable osservabile (file, comando, test che passa). Niente prosa qui. #### `## 0. Prerequisiti e gating` Cosa deve essere vero PRIMA di iniziare A1. Checklist. #### `## 1. Fase A — Rewrite Python (host Windows attuale)` Per ogni step da A1 ad A5: - `### A — ` - `**Obiettivo**:` 1 frase. - `**Input / dipendenze**:` step precedenti, file, env vars. - `**Attività**:` checklist `- [ ]` granulare (5–15 voci tipiche), ognuna con deliverable osservabile. - `**Hook futuri Fase C**:` cosa deve essere progettato adesso per non bloccare ESXi (es. firma del Protocol `VmBackend`, separazione `clone_linked` da `start`, niente assunzione "stesso host"). - `**Test / validazione**:` comandi e criteri pass/fail concreti (pytest target, coverage minima, smoke workflow Gitea da triggerare). - `**Rollback**:` come tornare allo stato precedente lo step. - `**Definizione di fatto step A**:` checklist `- [ ]` di chiusura (max 5 voci). #### `## 2. Fase B — Migrazione host Linux Mint` Stessa struttura per gli step da B1 a B8. In più: - Marca esplicitamente quali step sono **eseguibili in parallelo** ad A (B1 setup hardware Linux può iniziare durante A3/A4) e quali sono **strettamente sequenziali** (B6 cutover dopo "A done"). - Per ogni step indica **rischi specifici** presi da `idea-2-linux-host.md` §6 e mitigazioni. #### `## 3. Step trasversali (X)` Step che attraversano A e B (test, docs, observability, sicurezza, gestione credenziali headless, lint dual-stack PSSA+ruff). Stessa struttura per ogni X. #### `## 4. Hook architetturali per Fase C` Lista esplicita dei punti del codice/config che restano "aperti" per ESXi: Protocol `VmBackend`, selezione backend via `config.toml`, separazione control plane / compute, naming neutro (no `vmrun_*` nei nomi pubblici delle API). **Niente implementazione** — solo contratto di design da non violare. #### `## 5. Cronoprogramma e dipendenze` Diagramma Mermaid `gantt` o `flowchart` con le dipendenze tra step A1…A5, B1…B8, X1…Xn. **Niente date assolute, niente stime di durata in giorni**: usa solo numerazione di sequenza e dipendenze logiche. #### `## 6. Matrice rischi consolidata` Tabella `Rischio | Fase | Severità | Mitigazione | Owner action item`. Unisci §7 di idea-1 e §6 di idea-2, aggiungi rischi di integrazione A↔B che emergono solo nel piano fuso (es. shim PowerShell che assume path Windows e si rompe in Fase B). #### `## 7. Definizione di "fatto" globale (A+B)` Una checklist finale `- [ ]` che combina §8 di idea-1 + §8 di idea-2, deduplicata e coerente con la checklist master in testa. #### `## 8. Riferimenti` Link relativi ai file originali letti. ### Regole stilistiche e di contenuto 1. **Lingua**: italiano tecnico, coerente con i piani esistenti. 2. **Tono**: imperativo / dichiarativo, niente "potremmo", "si potrebbe". Ogni attività è un'azione concreta con deliverable. 3. **Niente stime di tempo / date / sprint**. Solo dipendenze logiche. 4. **Niente nuovi vincoli inventati**: tutto quello che dichiari deve essere derivabile dai 6 file di riferimento o dallo stato attuale del repo. Se proponi qualcosa di nuovo, marcalo con `> NOTA NUOVA:` e spiega perché. 5. **Coerenza con `AGENTS.md`**: ogni step PowerShell residuo deve rispettare PS 5.1 (no `??`, no `&&`, ecc.); ogni nuova decisione che supera un errore frequente (#1–#12) deve dichiararlo esplicitamente. 6. **Checklist machine-friendly**: usa esclusivamente `- [ ]` (con spazio, non `- [x]`). Una voce per riga. Niente sub-checklist annidate oltre il primo livello dentro la stessa sezione. 7. **Tabelle**: usa pipe-tables Markdown standard. Nessun HTML. 8. **Mermaid**: un solo diagramma in §5, sintassi valida. 9. **Lunghezza target**: 600–1100 righe Markdown. Sotto le 500 è troppo sintetico, sopra le 1300 stai duplicando i piani originali. 10. **Auto-verifica finale**: alla fine del documento, prima di §8, aggiungi una sezione `## 7.1 Auto-check` con queste domande a cui il documento stesso deve poter rispondere "sì" leggendolo: - Ogni voce della checklist master compare almeno una volta come `- [ ]` dentro lo step corrispondente? - Ogni step A/B/X ha tutte le sottosezioni richieste? - I 12 errori frequenti di `AGENTS.md` sono stati indirizzati o dichiarati non applicabili? - Gli hook §4 sono coerenti con `idea-3-esxi-support.md` §3? ### Cosa NON devi fare - Non implementare codice. Solo piano. - Non duplicare integralmente i contenuti di idea-1/idea-2: cita e riassumi. - Non introdurre tecnologie nuove non già menzionate (no Ansible, no Terraform, no Docker host-side, no K8s) salvo `> NOTA NUOVA:` motivata. - Non modificare altri file del repo. Solo creazione di `plans/implementation-plan-A-B.md`. - Non includere date, settimane, story point, t-shirt sizing. ### Output atteso Un solo file: `plans/implementation-plan-A-B.md`, conforme alla struttura sopra, pronto per essere committato. Nessun testo conversazionale fuori dal file.