local-ci-cd-system/plans/archived/2026-05-23/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](../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<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<n>.

#### `## 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<n>/B<n>/X<n> 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.