local-ci-cd-system/plans/prompt-implementation-plan-A-B.md

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 — 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 — razionale, ordine, criteri di "fase completata", strategia di rollback.
3. plans/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 — Fase B (decisione hypervisor, mappa di adattamento, step B1–B8, rischi, fatto).
5. plans/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/CI-FLOW.md, docs/HOST-SETUP.md, docs/RUNBOOK.md per capire layout e operatività attuali.
7. La cartella scripts/ e 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<n> — <titolo>
• **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<n>**: 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.