feat: enhance documentation and scripts for in-VM Git cloning and template setup

- Updated README.md to reflect the new in-VM git clone feature with `-UseGitClone`. - Modified Setup-Host.ps1 to correct VMX path references. - Revised various documentation files (ARCHITECTURE.md, CI-FLOW.md, HOST-SETUP.md, WINDOWS-TEMPLATE-SETUP.md) to include updated paths and features. - Added Setup-GiteaSSH.md for SSH configuration instructions. - Archived outdated documentation and updated README.md for clarity on current resources.
2026-05-10 23:03:56 +02:00
parent a60f7a4b90
commit 90a4396443
12 changed files with 114 additions and 64 deletions
@@ -2,7 +2,7 @@

 Sistema CI/CD self-hosted su Windows per build isolati in VM efimere VMware.

-**Stato**: production-ready — e2e verificato (e2e-009 SUCCESS)
+**Stato**: production-ready — e2e verificato (e2e-009 SUCCESS); §3.3 in-VM git clone attivabile via `-UseGitClone` (e2e PASS, -25.7% vs baseline)

 ---

@@ -49,7 +49,7 @@ Ogni build gira in una VM Windows Server 2025 **usa e getta**, ripristinata dall
 | Componente | Versione |
 |---|---|
 | OS | Windows Server 2025 |
-| VMX | `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx` |
+| VMX | `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx` (path in `runner/config.yaml` → `GITEA_CI_TEMPLATE_PATH`) |
 | VS Build Tools | 2026 (MSBuild 18.5.4 / toolset v145) |
 | .NET SDK | 10.0.203 |
 | Python | 3.13.3 |
@@ -62,36 +62,58 @@ Ogni build gira in una VM Windows Server 2025 **usa e getta**, ripristinata dall

 ```
 ├── Setup-Host.ps1                # Bootstrap host: dirs F:\CI\, credenziali, act_runner service
+├── PSScriptAnalyzerSettings.psd1 # Regole linting condivise (§5.4)
 │
 ├── scripts/
-│   ├── Invoke-CIJob.ps1          # Orchestratore principale
+│   ├── _Common.psm1              # Shared module (vmrun wrapper, session opts) §5.2
+│   ├── Invoke-CIJob.ps1          # Orchestratore principale (-UseGitClone opt-in §3.3)
 │   ├── New-BuildVM.ps1           # Linked clone da template
-│   ├── Wait-VMReady.ps1          # Polling WinRM readiness
-│   ├── Invoke-RemoteBuild.ps1    # Zip transfer + esecuzione build in VM
+│   ├── Wait-VMReady.ps1          # Polling WinRM HTTPS readiness
+│   ├── Invoke-RemoteBuild.ps1    # Zip transfer (o git clone in VM) + build via WinRM
 │   ├── Get-BuildArtifacts.ps1    # Copia artifacts dall'host
-│   └── Remove-BuildVM.ps1        # Stop + rimozione VM clone
+│   ├── Remove-BuildVM.ps1        # Stop + rimozione VM clone (-WhatIf)
+│   ├── Cleanup-OrphanedBuildVMs.ps1   # Cleanup VM orfane (§2.2)
+│   ├── Invoke-RetentionPolicy.ps1     # Retention artifact + log (§2.3)
+│   ├── Watch-DiskSpace.ps1            # Alert spazio libero F: (§4.3)
+│   ├── Watch-RunnerHealth.ps1         # Health check runner (§2.7)
+│   ├── Backup-CITemplate.ps1          # Backup VMDK template (§2.6)
+│   ├── Set-TemplateSharedFolders.ps1  # Cache NuGet/pip via shared folders (§3.1)
+│   ├── Measure-CIBenchmark.ps1        # Benchmark fasi pipeline (§3.6)
+│   └── Register-CIScheduledTasks.ps1  # Task Scheduler bootstrap
 │
 ├── template/
-│   ├── Prepare-WinBuild2025.ps1 # Provisioning automatico template VM (HOST-side)
-│   └── Setup-WinBuild2025.ps1    # Installazione toolchain nella VM (GUEST-side)
+│   ├── Deploy-WinBuild2025.ps1   # Install Windows unattended + OS hardening (HOST)
+│   ├── Prepare-WinBuild2025.ps1  # Provisioning template VM (HOST-side)
+│   ├── Setup-WinBuild2025.ps1    # Installazione toolchain nella VM (GUEST-side)
+│   ├── Validate-DeployState.ps1  # Validazione stato post-Deploy
+│   └── Validate-SetupState.ps1   # Validazione stato post-Setup (pre-snapshot)
+│
+├── tests/                        # Pester v5 unit tests (§5.1)
 │
 ├── gitea/
 │   ├── workflows/
-│   │   └── build-nsis.yml        # Workflow live per nsis-plugin-nsinnounp
+│   │   ├── build-nsis.yml        # Workflow live per nsis-plugin-nsinnounp
+│   │   └── lint.yml              # PSScriptAnalyzer su push/PR (§5.4)
 │   └── workflow-example.yml      # Template generico adattabile
 │
 ├── runner/
-│   └── config.yaml               # Configurazione act_runner (no secrets)
+│   ├── config.yaml               # Configurazione act_runner (no secrets)
+│   └── Install-Runner.ps1
 │
 ├── docs/
 │   ├── ARCHITECTURE.md           # Diagramma sistema e componenti
 │   ├── CI-FLOW.md                # Flusso dettagliato passo-passo
+│   ├── HOST-SETUP.md             # Bootstrap macchina host
+│   ├── WINDOWS-TEMPLATE-SETUP.md # Provisioning template Windows
+│   ├── LINUX-TEMPLATE-SETUP.md   # Bozza template Linux (§6.1, non implementato)
 │   ├── OPTIMIZATION.md           # Layout disco, snapshot, cache, tuning
-│   ├── BEST-PRACTICES.md         # Sicurezza, WinRM, credenziali
-│   └── Setup-GiteaSSH.md         # Configurazione SSH alias per Gitea
+│   ├── BEST-PRACTICES.md         # Sicurezza, WinRM, credenziali, threat model
+│   ├── RUNBOOK.md                # Triage incident comuni (§4.4)
+│   ├── TEST-PLAN-v1.3-to-HEAD.md # Test plan completo features post-v1.3
+│   ├── Setup-GiteaSSH.md         # Configurazione SSH alias per Gitea
+│   └── archived/                 # Doc storici / sign-off
 │
-├── PLAN.md                       # Stato implementazione e decisioni tecniche
-└── TODO.md                       # Task completati e roadmap futura
+└── TODO.md                       # Roadmap, audit trail task completati, backlog
 ```

 ---
@@ -131,10 +153,12 @@ nssm start act_runner
 Imposta `GITEA_CI_TEMPLATE_PATH` nelle variabili d'ambiente del servizio:
 `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx`

+Dettagli completi: [docs/HOST-SETUP.md](docs/HOST-SETUP.md).
+
 ### 4. SSH per Gitea

 Vedi [docs/Setup-GiteaSSH.md](docs/Setup-GiteaSSH.md) per configurare l'alias `gitea-ci`
-(SSH port 2222, necessario per `git clone ssh://gitea-ci/...` durante i build).
+(SSH port 2222, usato dai workflow live in `git clone ssh://gitea-ci/...`).

 ---

@@ -153,7 +177,9 @@ Vedi [docs/Setup-GiteaSSH.md](docs/Setup-GiteaSSH.md) per configurare l'alias `g
  -GuestCredentialTarget 'BuildVMGuest'
 ```

-Artifacts raccolti in: `F:\CI\Artifacts\test-001\artifacts.zip`
+Artifacts raccolti in: `F:\CI\Artifacts\test-001\artifacts.zip`.
+
+Aggiungi `-UseGitClone` per clonare direttamente in VM (skip host-zip-transfer; richiede Git+7-Zip in template — già inclusi nel Tier-1 Toolchain §6.6).

 ---

@@ -173,9 +199,15 @@ e aggiorna `-RepoUrl`, `-BuildCommand` e `-GuestArtifactSource`.
 |---|---|
 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Diagramma componenti e flusso dati |
 | [docs/CI-FLOW.md](docs/CI-FLOW.md) | Descrizione dettagliata di ogni fase del pipeline |
-| [docs/OPTIMIZATION.md](docs/OPTIMIZATION.md) | Layout NVMe, snapshot strategy, cache, tuning WinRM |
-| [docs/BEST-PRACTICES.md](docs/BEST-PRACTICES.md) | Sicurezza WinRM, gestione credenziali, isolamento |
+| [docs/HOST-SETUP.md](docs/HOST-SETUP.md) | Bootstrap macchina host (Setup-Host.ps1) |
+| [docs/WINDOWS-TEMPLATE-SETUP.md](docs/WINDOWS-TEMPLATE-SETUP.md) | Provisioning template Windows (Deploy + Prepare + Setup) |
+| [docs/LINUX-TEMPLATE-SETUP.md](docs/LINUX-TEMPLATE-SETUP.md) | Bozza template Linux (§6.1, non implementato) |
+| [docs/OPTIMIZATION.md](docs/OPTIMIZATION.md) | Layout NVMe, snapshot strategy, cache, tuning |
+| [docs/BEST-PRACTICES.md](docs/BEST-PRACTICES.md) | Sicurezza WinRM, threat model, credenziali |
+| [docs/RUNBOOK.md](docs/RUNBOOK.md) | Triage incident comuni (runner offline, clone fail, ecc.) |
+| [docs/TEST-PLAN-v1.3-to-HEAD.md](docs/TEST-PLAN-v1.3-to-HEAD.md) | Test plan completo features post-v1.3 |
 | [docs/Setup-GiteaSSH.md](docs/Setup-GiteaSSH.md) | Configurazione SSH alias `gitea-ci` |
+| [TODO.md](TODO.md) | Roadmap, audit trail task completati, backlog |

 ---

@@ -185,4 +217,4 @@ WinRM usa **HTTPS/5986** con certificato self-signed e Basic auth.
 `-SkipCACheck`/`-SkipCNCheck` sono accettabili in lab isolato (il cert non è di una CA trusted).
 Per ambienti condivisi o di produzione, usare un certificato CA valida e rimuovere `-SkipCACheck`.
 Vedi [docs/BEST-PRACTICES.md](docs/BEST-PRACTICES.md).
-
+
@@ -339,7 +339,7 @@ Write-Host "    $CIRoot\ISO\"
 Write-Host ""
 Write-Host " 3. Provision the template VM:"
 Write-Host "    a. Create VM in VMware Workstation (4 vCPU, 6 GB RAM, 80 GB thin)"
-Write-Host "       VMX: $CIRoot\Templates\WinBuild\WinBuild2025.vmx"
+Write-Host "       VMX: $CIRoot\Templates\WinBuild2025\WinBuild2025.vmx"
 Write-Host "       NIC: VMnet8 (NAT) — internet required during provisioning"
 Write-Host "    b. Install Windows Server 2025 + enable WinRM inside VM"
 Write-Host "    c. From this host run:"
@@ -354,4 +354,4 @@ Write-Host ""
 Write-Host " 5. Verify act_runner is Online in Gitea:"
 Write-Host "    $GiteaUrl/-/admin/runners"
 Write-Host ""
-
+
@@ -31,12 +31,12 @@ _Last updated: 2026-05-10 (post Sprint 8: §3.3 e2e PASS — 34s/25.7% faster,
 | [ ]   | Gitea Workflow Integration      |    4 |    1 | manca solo §P3 generalizzazione workflow                      |
 | [x]   | §1 Sicurezza & hardening        |    3 |    0 | 1.1, 1.4, 1.6 done; 1.2/1.3/1.5/1.7/1.8 deferred (home lab)   |
 | [x]   | §2 Affidabilità & resilienza    |    7 |    0 | tutto done (2.1-2.7)                                          |
-| [x]   | §3 Performance & throughput     |    4 |    0 | 3.1/3.2/3.3/3.6 done; 3.4/3.5 deferred — **§3 CHIUSO**       |
+| [x]   | §3 Performance & throughput     |    4 |    0 | 3.1/3.2/3.3/3.6 done; 3.4/3.5 deferred — **§3 CHIUSO**        |
 | [x]   | §4 Osservabilità & manutenzione |    3 |    0 | 4.1/4.3/4.4 done (4.2 Prometheus, 4.5 Dashboard rimossi)      |
 | [x]   | §5 Qualità codice & test        |    5 |    0 | 5.1/5.2/5.3/5.4/5.5 done                                      |
-| [ ]   | §6 Scalabilità & estensioni     |    1 |    5 | 6.6 Tier-1 (Git+7-Zip) done; 6.1 (Linux), 6.2-6.5 TODO       |
+| [ ]   | §6 Scalabilità & estensioni     |    1 |    5 | 6.6 Tier-1 (Git+7-Zip) done; 6.1 (Linux), 6.2-6.5 TODO        |
 | [ ]   | §7 Refactor Deploy ↔ Setup      |    4 |    1 | 7.1/7.2/7.3/7.4 done; 7.5 (rinomina) opzionale                |
-| [x]   | In-VM Git Clone (§3.3)          |    4 |    0 | COMPLETATO 2026-05-10 — e2e PASS: 34s/25.7% vs baseline      |
+| [x]   | In-VM Git Clone (§3.3)          |    4 |    0 | COMPLETATO 2026-05-10 — e2e PASS: 34s/25.7% vs baseline       |
 | [ ]   | Linux Build VM (§6.1)           |    0 |    4 | bozza in `docs/LINUX-TEMPLATE-SETUP.md`                       |

 **Prossimi passi consigliati** (vedi anche "Suggerimento di sequencing" in fondo):
@@ -69,7 +69,7 @@ _Last updated: 2026-05-10 (post Sprint 8: §3.3 e2e PASS — 34s/25.7% faster,
  - [x] `F:\CI\act_runner\`
  - [x] `F:\CI\Cache\NuGet\`
  - [x] `F:\CI\RunnerWork\`
-  - [x] `F:\CI\Templates\WinBuild\`
+  - [x] `F:\CI\Templates\WinBuild2025\`
  - [x] `F:\CI\Logs\` — log per job (retention: 30 giorni)
  - [x] `F:\CI\ISO\` — contiene `26100.1742.240906-0331.ge_release_svc_refresh_SERVER_VOL_x64FRE_en-us.iso` (Windows Server 2025)

@@ -84,7 +84,7 @@ _Last updated: 2026-05-10 (post Sprint 8: §3.3 e2e PASS — 34s/25.7% faster,
  ### Fase A — Crea e installa la VM (NIC: NAT per internet)
  - [x] Crea nuova VM in VMware Workstation con queste impostazioni:
        - 4 vCPU, 6144 MB RAM, disco 80 GB thin
-        - VMX path: `F:\CI\Templates\WinBuild\WinBuild2025.vmx`
+        - VMX path: `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx`
        - **NIC: VMnet8 (NAT)** ← internet necessario per Windows Update e installer
        - CD-ROM: `F:\CI\ISO\26100.1742.240906-0331.ge_release_svc_refresh_SERVER_VOL_x64FRE_en-us.iso`
  - [x] Installa Windows Server 2025 dall'ISO
@@ -516,18 +516,18 @@ build più ampi senza toccare il template.

 ### Tier-2 (backlog) — tool da aggiungere come ulteriori step `Setup-WinBuild2025` (ognuno con `Assert-Step`):

-| Tool                | Versione                | Razionale                                                      |
-| ------------------- | ----------------------- | -------------------------------------------------------------- |
+| Tool                | Versione                | Razionale                                                          |
+| ------------------- | ----------------------- | ------------------------------------------------------------------ |
 | **Git for Windows** | 2.54.0.windows.1        | [x] Self-clone in VM (alt a host-zip-transfer), submodule fetch    |
 | **7-Zip**           | 26.01                   | [x] Universale unpack/zip; molti installer e workflow ne dipendono |
 | **PowerShell 7.x**  | latest LTS              | [ ] Più veloce di 5.1, parallel pipelines, operatori moderni       |
-| **NSIS**            | latest                  | Test build installer (es. `nsis-plugin-nsinnounp`)             |
-| **CMake**           | latest                  | Build system cross-platform per progetti C/C++ nativi          |
-| **Node.js LTS**     | latest LTS              | Frontend/Electron pipelines, JS toolchain (npm)                |
-| **WiX Toolset**     | v4 stable               | MSI building da .NET projects                                  |
-| **gh CLI**          | latest                  | Upload artifact a release Gitea/GitHub, comment PR             |
-| **Sysinternals**    | sysinternals.com `live` | Diagnostica process/handle quando build flaky                  |
-| **vcpkg**           | latest                  | Package manager C++ per dipendenze native                      |
+| **NSIS**            | latest                  | Test build installer (es. `nsis-plugin-nsinnounp`)                 |
+| **CMake**           | latest                  | Build system cross-platform per progetti C/C++ nativi              |
+| **Node.js LTS**     | latest LTS              | Frontend/Electron pipelines, JS toolchain (npm)                    |
+| **WiX Toolset**     | v4 stable               | MSI building da .NET projects                                      |
+| **gh CLI**          | latest                  | Upload artifact a release Gitea/GitHub, comment PR                 |
+| **Sysinternals**    | sysinternals.com `live` | Diagnostica process/handle quando build flaky                      |
+| **vcpkg**           | latest                  | Package manager C++ per dipendenze native                          |

 **Approccio**:
 - Pinning hash SHA256 per ogni installer (vedi §1.3)
@@ -806,7 +806,7 @@ alla successiva.
 | act_runner                | `F:\CI\act_runner\act_runner.exe` (servizio: `act_runner`)   |
 | act_runner config         | `F:\CI\act_runner\config.yaml`                               |
 | act_runner logs           | `F:\CI\act_runner\logs\`                                     |
-| Template VMX              | `F:\CI\Templates\WinBuild\WinBuild2025.vmx`                   |
+| Template VMX              | `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx`                   |
 | Snapshot name             | `BaseClean`                                                  |
 | Clone base dir            | `F:\CI\BuildVMs\`                                            |
 | Artifact dir              | `F:\CI\Artifacts\`                                           |
@@ -117,7 +117,7 @@ The runner host **never executes build tools directly**. Its only role is orches
 - .NET SDK **10.0.203**
 - Python **3.13.3** (per build script personalizzati come `build_plugin.py`)
 - NuGet CLI (optional, dotnet restore covers most cases)
- Git: NOT installed by default — source arrives via WinRM zip transfer. See TODO.md `-UseGitClone` for the in-VM git clone opt-in path.
+- **Git for Windows 2.54** + **7-Zip 26.01** (Tier-1 toolchain, §6.6 — DONE 2026-05-10): consente l'opt-in `-UseGitClone` di `Invoke-CIJob.ps1` per clonare il repository direttamente in VM (skip host zip transfer, e2e PASS, -25.7% durata pipeline).

 ---

@@ -191,4 +191,5 @@ VMs have internet access via NAT — required for pip/nuget during build.
 - WinRM credentials are stored in Windows Credential Manager on host (not hardcoded)
 - Each VM is fully destroyed after the job — no state carries between builds
 - Runner host does not expose any ports to the build VM network
- Source code is transferred via zip (Compress-Archive → WinRM copy → Expand-Archive in guest) — no PAT is ever present inside the VM; VMs have NAT internet for pip/nuget at build time
+- Source code is transferred via zip (Compress-Archive → WinRM copy → Expand-Archive in guest) by default — no PAT is ever present inside the VM; VMs have NAT internet for pip/nuget at build time.
+- With `-UseGitClone` (§3.3, opt-in) il clone avviene dentro la VM via SSH alias `gitea-ci` (forwardato dall'host); la chiave privata SSH dell'host non viene esposta al guest — vedi BEST-PRACTICES.md per il threat model.
@@ -138,8 +138,11 @@ Sequence inside the PSSession:

 ```
 1. New-PSSession  →  open WinRM session to VM
-2. Compress-Archive (host) → copy zip to C:\CI\build.zip (guest) → Expand-Archive to C:\CI\build\
-   (source code è già clonato sull'host in Phase 1 — non si fa git clone nella VM)
+2a. (default) Compress-Archive (host) → copy zip to C:\CI\build.zip (guest) → Expand-Archive to C:\CI\build\
+    (source code è già clonato sull'host in Phase 1 — nessun git clone nella VM)
+2b. (opt-in, `-UseGitClone`, §3.3 DONE 2026-05-10)
+    git clone direttamente in VM tramite `ssh://gitea-ci/...` (richiede Git+7-Zip in template, §6.6 Tier-1)
+    Vantaggio: skip host-zip-transfer, -25.7% durata pipeline (e2e PASS). Verifica SHA commit post-clone.
 3. Invoke-Expression "$BuildCommand" in C:\CI\build\
     Esempio: python build_plugin.py --final --dist-dir dist
       a. Build 4 configurazioni MSBuild in parallelo (x86-unicode, x64-unicode, cli-x86, cli-x64)
@@ -33,13 +33,13 @@ F:\CI\
 ├── Artifacts\              # output build raccolti dall'host
 ├── Logs\                   # log per-job (retention: 30 giorni)
 ├── Templates\
-│   └── WinBuild\           # VMX template Windows (immutabile dopo snapshot)
+│   └── WinBuild2025\       # VMX template Windows (immutabile dopo snapshot)
 ├── act_runner\
 │   ├── act_runner.exe      # binario runner Gitea
 │   ├── config.yaml         # config runner (path, label, capacity)
 │   └── logs\               # stdout/stderr del servizio
 ├── Cache\
-│   └── NuGet\              # cache NuGet condivisa via shared folder (TODO §3.1)
+│   └── NuGet\              # cache NuGet condivisa via shared folder (§3.1 — DONE 2026-05-10, vedi scripts/Set-TemplateSharedFolders.ps1)
 ├── RunnerWork\             # working dir di act_runner (job staging)
 └── ISO\                    # ISO di installazione (Windows Server 2025, ecc.)
 ```
@@ -161,13 +161,13 @@ Allo `Setup-Host.ps1` exit 0:

 ## Maintenance & operational tasks

-Voci di backlog (vedi [TODO.md](../TODO.md)):
+Task schedulati (vedi `scripts/Register-CIScheduledTasks.ps1` per il bootstrap):

- **§2.2** Cleanup VM orfane schedulato (`scripts/Cleanup-OrphanedBuildVMs.ps1` ogni 6h, `-MaxAgeHours 4`)
- **§2.3** Retention artifact + log (Artifacts > 30 gg, Logs > 30 gg, guard libero < 50 GB)
- **§2.7** Health check runner (query API Gitea ogni 15 min, restart su offline)
- **§4.3** Disk space alert (`F:` < 50 GB → eventcreate/webhook)
- **§1.2** Restringere `TrustedHosts` da `*` a `192.168.79.*`
+- **§2.2** Cleanup VM orfane (`scripts/Cleanup-OrphanedBuildVMs.ps1`, ogni 6h, `-MaxAgeHours 4`)
+- **§2.3** Retention artifact + log (`scripts/Invoke-RetentionPolicy.ps1`, daily)
+- **§2.6** Backup template (`scripts/Backup-CITemplate.ps1`, weekly)
+- **§2.7** Health check runner (`scripts/Watch-RunnerHealth.ps1`, ogni 15 min)
+- **§4.3** Disk space alert (`scripts/Watch-DiskSpace.ps1`, ogni ora)

 ---

@@ -104,7 +104,7 @@ F:\CI\Cache\NuGet\   ← shared folder on host

 ### VMware Shared Folder Configuration (in template VMX)

-Add to `WinBuild.vmx` before taking the `BaseClean` snapshot:
+Add to `WinBuild2025.vmx` before taking the `BaseClean` snapshot:
 ```ini
 sharedFolder0.present = "TRUE"
 sharedFolder0.enabled = "TRUE"
@@ -7,14 +7,14 @@ Organized by sprint area with pre-requisites, test steps, and pass/fail criteria

 ## Overview

-| Area                          | Items                   | Status   | Baseline                                                                               |
-| ----------------------------- | ----------------------- | -------- | -------------------------------------------------------------------------------------- |
-| **Sprint 2** (Reliability)    | 2.1/2.2/2.3/2.5         | Partial  | §2.2/§2.3 validated locally 2026-05-10; §2.1/§2.5 need real VMs                       |
-| **Sprint 3** (Observability)  | 4.1/4.3/4.4             | Partial  | §4.3/§4.4 validated locally 2026-05-10; §4.1 (JSONL) needs real build job             |
-| **Sprint 4-6** (Quality/Perf) | 1.4/3.1/3.6/5.2/5.3/5.4 | Partial  | §1.4/§5.2/§5.3/§5.4 validated 2026-05-10; §3.1/§3.6 need real VMs                    |
-| **Sprint 7** (Testing)        | 5.1                     | [x] Done | 22/22 Pester tests passing in 12.9s (2026-05-10)                                      |
-| **§1.6** (Docs)               | Threat model            | [x] Done | BEST-PRACTICES.md verified 2026-05-10                                                  |
-| **§3.2** (Perf)               | 7-Zip compression       | Partial  | Fallback path validated; in-VM 7-Zip speed test needs real VM                         |
+| Area                          | Items                   | Status   | Baseline                                                                  |
+| ----------------------------- | ----------------------- | -------- | ------------------------------------------------------------------------- |
+| **Sprint 2** (Reliability)    | 2.1/2.2/2.3/2.5         | Partial  | §2.2/§2.3 validated locally 2026-05-10; §2.1/§2.5 need real VMs           |
+| **Sprint 3** (Observability)  | 4.1/4.3/4.4             | Partial  | §4.3/§4.4 validated locally 2026-05-10; §4.1 (JSONL) needs real build job |
+| **Sprint 4-6** (Quality/Perf) | 1.4/3.1/3.6/5.2/5.3/5.4 | Partial  | §1.4/§5.2/§5.3/§5.4 validated 2026-05-10; §3.1/§3.6 need real VMs         |
+| **Sprint 7** (Testing)        | 5.1                     | [x] Done | 22/22 Pester tests passing in 12.9s (2026-05-10)                          |
+| **§1.6** (Docs)               | Threat model            | [x] Done | BEST-PRACTICES.md verified 2026-05-10                                     |
+| **§3.2** (Perf)               | 7-Zip compression       | Partial  | Fallback path validated; in-VM 7-Zip speed test needs real VM             |

 ---

@@ -37,7 +37,7 @@ credenziali archiviate, ISO Windows Server presente).
 | RAM                     | 6144 MB (6 GB)                                                  |
 | Disco                   | 80 GB thin provisioned                                          |
 | NIC                     | **VMnet8 (NAT)** — internet richiesto per WU + installer        |
-| VMX path                | `F:\CI\Templates\WinBuild\WinBuild2025.vmx`                      |
+| VMX path                | `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx`                      |
 | ISO                     | Windows Server 2025 (da `F:\CI\ISO\`)                           |

 ---
@@ -48,7 +48,7 @@ credenziali archiviate, ISO Windows Server presente).
 - File → New Virtual Machine → Custom
 - Hardware: 4 vCPU, 6144 MB, 80 GB thin
 - Network: **VMnet8 (NAT)**
- VMX: `F:\CI\Templates\WinBuild\WinBuild2025.vmx`
+- VMX: `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx`
 - CD/DVD: monta ISO Windows Server 2025

 ### A.2 Installa Windows Server 2025
@@ -219,7 +219,7 @@ Final    Pre-snapshot gate — 7 check cross-cutting + no installer leftover
   - VM → Snapshot → Take Snapshot
   - **Nome esatto: `BaseClean`** (case-sensitive, usato da `New-BuildVM.ps1`)
 3. **Lascia la VM spenta** — non modificarla mai più dopo lo snapshot
-4. **Verifica `runner/config.yaml`**: `GITEA_CI_TEMPLATE_PATH=F:\CI\Templates\WinBuild\WinBuild2025.vmx`
+4. **Verifica `runner/config.yaml`**: `GITEA_CI_TEMPLATE_PATH=F:\CI\Templates\WinBuild2025\WinBuild2025.vmx`

 ---

@@ -4,9 +4,15 @@ Date: 2026-05-10

 ## Archived Files

-### Setup-GiteaSSH.md
-**Reason**: Obsolete — current workflow uses HTTP URLs + credential manager for Gitea access, not SSH key-based authentication.
-**When to revisit**: If SSH-based Git clones become necessary (e.g., for server-to-server scenarios).
+### PLAN.md (archived 2026-05-10)
+**Reason**: Pianificazione iniziale (ultimo update 2026-05-08) superata dallo stato post Sprint 8.
+Stato corrente del sistema, decisioni tecniche e roadmap sono ora distribuiti tra:
+- `TODO.md` (root) per audit trail, summary status e backlog
+- `docs/ARCHITECTURE.md` per il design del sistema
+- `docs/CI-FLOW.md` per il flusso operativo
+- `docs/RUNBOOK.md` per il triage incident
+
+Resta come riferimento storico.

 ### TEST-7.4-e2e.md
 **Reason**: Sprint 7.4 refactor validation document. Specific to §7.4 Deploy↔Setup refactor completion testing.
@@ -16,6 +22,13 @@ Date: 2026-05-10
 - Post-refactor sign-off checklist
 **Useful for**: §6.6 (Toolchain Tier-1) template updates, Linux template setup (§6.1)

+## De-archived
+
+### Setup-GiteaSSH.md (restored 2026-05-10)
+Originariamente archiviato come "obsolete (HTTP+credential manager)" ma di fatto il workflow
+live (`gitea/workflows/build-nsis.yml`) e `Setup-Host.ps1` continuano a usare l'alias SSH
+`gitea-ci` (porta 2222) per i clone Git. Ripristinato in `docs/Setup-GiteaSSH.md`.
+
 ## Active Documentation

 All current, operational docs remain in parent directory:
@@ -24,7 +37,8 @@ All current, operational docs remain in parent directory:
 - CI-FLOW.md
 - HOST-SETUP.md
 - WINDOWS-TEMPLATE-SETUP.md
+- LINUX-TEMPLATE-SETUP.md (draft for §6.1)
 - OPTIMIZATION.md
 - RUNBOOK.md
 - TEST-PLAN-v1.3-to-HEAD.md
- LINUX-TEMPLATE-SETUP.md (draft for §6.1)
+- Setup-GiteaSSH.md