# SVG Framework - Valutazione Fase 4 (Asset libraries locali e indicizzazione)

Versione: 2026-04-24
Stato: decisione consolidata pre-implementazione (post completamento Fase 3)

---

## 1) Obiettivo della valutazione

Decidere se conviene introdurre in modo operativo:

- librerie SVG locali (repo o submodule);
- indicizzazione locale machine-readable;
- regole minime di licenza/manutenzione.

La valutazione e' allineata ai criteri della roadmap Fase 4:

- evidenza che Fase 1-3 non bastano;
- licenze e manutenzione chiarite;
- automazione minima anti-degrado;
- impatto repo accettabile.

---

## 2) Baseline osservata (stato repository)

Rilevazioni al 2026-04-22:

- `skills/svg/assets/` non presente (stato pre-implementazione valutato in quel momento);
- `.gitmodules` non presente;
- nessuno script dedicato ad asset indexing in `scripts/`;
- skill SVG attuale dichiara esplicitamente out-of-scope: asset libraries/submodule.

Conseguenza: Fase 4 non e' ancora iniziata lato implementazione; la decisione e' ancora pienamente reversibile.

---

## 3) Opzioni architetturali valutate

### Opzione A - Copia diretta asset nel repo principale

Pro:

- onboarding immediato, nessun comando submodule.

Contro:

- crescita rapida peso repository;
- aggiornamenti rumorosi (molti file);
- rischio alto di drift e conflitti.

Valutazione sintetica: **sconsigliata** salvo subset molto piccolo e statico.

### Opzione B - Librerie come git submodule + indice locale

Pro:

- pinning per commit (riproducibilita');
- controllo aggiornamenti per libreria;
- peso storico repo principale piu' contenuto.

Contro:

- onboarding leggermente piu' complesso (`--recurse-submodules`);
- necessita policy esplicita su update cadence.

Valutazione sintetica: **opzione raccomandata come base**, con possibile estensione ibrida (submodule + vendor diretto) nel pilot.

### Opzione C - Nessun submodule, fetch remoto on-demand

Pro:

- repo leggero.

Contro:

- non deterministico;
- dipendenza runtime dalla rete/API;
- maggiore fragilita' cross-host.

Valutazione sintetica: **non allineata** alla governance local-first del programma.

---

## 4) Raccomandazione tecnica (governata)

Raccomandazione: **GO limitato a pilot Fase 4 con modello ibrido (Opzione B come base)**, non rollout completo.

Perimetro pilot suggerito:

- massimo 2 librerie (1 icone + 1 illustrazioni);
- adozione ibrida consentita: una libreria in submodule e una vendorizzata direttamente;
- indice locale unico `skills/svg/assets/index.json`;
- no integrazione in workflow illustrativo completo (Fase 5 resta separata);
- nessun refactor trasversale fuori `skills/svg/assets/`, `scripts/` e docs SVG.

---

## 5) Contratto minimo indice locale (proposto)

`skills/svg/assets/index.json` dovrebbe includere almeno:

- `schema_version` (stringa);
- `generated_at` (ISO 8601);
- `libraries[]` con:
  - `id`, `kind` (`icons|illustrations`), `source`, `license`;
  - `root_path` (path locale relativo);
  - `asset_count`;
  - `tags` opzionali;
- `assets[]` con:
  - `library_id`;
  - `relative_path`;
  - `name`;
  - `keywords` (array sempre con `items` coerenti lato schema).

Vincolo: indice orientato a discovery, non a duplicazione integrale dei metadata upstream.

---

## 6) Gate di accettazione consigliati

Gate A - Valore reale:

- almeno 3-5 casi concreti (interni) dove Fase 1-3 non copre il bisogno senza librerie locali.

Gate B - Licenze:

- licenza verificata per ogni libreria candidata;
- documento locale con policy uso/attribution/update.

Gate C - Impatto repo:

- dimensione repo principale stabile (submodule preferiti);
- nessun degrado su clone/onboarding oltre una complessita' accettabile.

Gate D - Automazione minima:

- script di build indice;
- script di check indice;
- script di search indice per uso agentico;
- smoke Fase 4 con esito machine-readable.

Gate E - Compatibilita':

- nessuna regressione dei workflow Fase 3;
- boundary Fase 4 esplicito nella skill/router.

---

## 7) Rischi e mitigazioni

Rischio: drift path tra skill e librerie.
Mitigazione: indice come source of truth + check automatico path esistenti.

Rischio: aggiornamenti submodule non governati.
Mitigazione: finestra update periodica + pin commit + changelog locale.

Rischio: confusione tra Fase 4 e Fase 5.
Mitigazione: mantenere fuori scope composizione avanzata e workflow illustrativo completo.

Rischio: compliance licenze incompleta.
Mitigazione: blocco merge se manca scheda licenza per una libreria.

---

## 8) Esito valutazione (2026-04-22)

Esito corrente:

- **NO-GO** a rollout pieno Fase 4;
- **GO** a pilot controllato con modello ibrido (`lucide` submodule, `open-peeps` vendored) + indicizzazione minima.

Promovibilita' verso `master` stimata dopo pilot: **media** (solo con gate A-E soddisfatti).

---

## 9) Librerie pilot selezionate (decisione consolidata)

Per il pilot Fase 4 vengono selezionate:

1. `lucide` (categoria `icons`, gestione `submodule`)
2. `open-peeps` (categoria `illustrations`, gestione `vendored`)

Razionale:

- copertura dei due domini target minimi (icone + illustrazioni);
- combinazione coerente con la visione SVG gia' documentata;
- perimetro ridotto e verificabile senza introdurre ampiezza eccessiva.

Nota licenze/compliance:

- nel pilot va mantenuta una scheda locale con riferimenti licenza upstream, attribution (se richiesta) e policy update;
- l'assenza di tali metadati blocca la promozione a rollout oltre il pilot.
- baseline operativa librerie: `docs/svg/svg-framework-phase4-pilot-libraries.md`.

---

## 10) Piano operativo minimo per avvio pilot

1. Definire 2 librerie candidate e validare licenze.
2. Introdurre `skills/svg/assets/` con baseline ibrida (`lucide` submodule, `open-peeps` vendored).
3. Implementare `scripts/build-svg-asset-index.js`.
4. Implementare `scripts/check-svg-asset-index.js`.
5. Aggiungere `scripts/smoke-svg-phase4.js` (profilo minimo).
6. Aggiornare docs skill/router con boundary Fase 4.

Done minimo pilot:

- indice generabile e validato;
- indice interrogabile da tool agent-facing;
- smoke Fase 4 pass;
- documentazione licenze/policy aggiornata;
- nessuna regressione Fase 3.

---

## 11) Chiusura pilot e librerie candidate future

Decisione per chiusura pilot:

- non introdurre ulteriori librerie nella Fase 4;
- mantenere `lucide` + `open-peeps` come perimetro sufficiente per coprire
  icone e illustrazioni leggere;
- promuovere Heroicons, Tabler e Phosphor solo a candidate future, non a
  requisito di chiusura.

Razionale:

- la valutazione iniziale limita il pilot a massimo 2 librerie;
- ogni nuova libreria aggiunge licenza, update policy, submodule/pinning,
  indicizzazione e smoke;
- Lucide copre gia' il bisogno primario di icone tecniche;
- Open Peeps copre il bisogno minimo di figure/illustrazioni leggere;
- il gap operativo piu' utile per l'agente non e' quantita' di asset, ma
  discovery rapida e verificabile dell'indice locale.

Tool specifico aggiunto per chiusura Fase 4:

- `skills/svg/tools/search-assets.js`: ricerca deterministica su
  `skills/svg/assets/index.json` con `--query`, `--library`, `--kind`,
  `--limit` e output JSON.