# SVG Framework Roadmap (branch dedicato, multi-fase)

Versione: 2026-04-27
Stato: roadmap attiva di progetto incubato su branch dedicato
Riferimento architetturale: `docs/svg/svg-framework-analysis.md`

Questo documento definisce il **piano operativo definitivo** per l'iniziativa SVG Framework nel repository `mcp-servers`.

L'obiettivo non e' trattare il framework SVG come una milestone singola da integrare direttamente nel ramo principale, ma come **progetto complesso multi-fase**, sviluppato inizialmente su un **branch dedicato** e promosso verso `master` solo per blocchi maturi, verificati e coerenti con l'architettura del repository.

L'analisi completa di contesto, use case, skill proposte, tooling e asset strategy resta documentata in:

- `docs/svg/svg-framework-analysis.md`

Questo file ha valore di **base architetturale**.
La presente roadmap ne deriva il **perimetro operativo**, i **boundary**, le **fasi**, i **criteri di accettazione** e la **strategia di integrazione**.

---

## 1) Decisione architetturale

### 1.1 Scelta

L'iniziativa SVG Framework viene gestita come:

- **progetto incubato multi-fase**;
- sviluppato inizialmente su **branch dedicato**;
- con promozione progressiva verso `master` solo delle componenti che superano i criteri di qualita', compatibilita' e manutenibilita'.

### 1.2 Motivazione

La proposta descritta in `docs/svg/svg-framework-analysis.md` e' valida come visione, ma troppo ampia per essere trattata come milestone singola. Include infatti, in un unico perimetro:

- skill specialistiche multiple;
- workflow di illustrazione e composizione;
- dipendenze CLI eterogenee;
- asset libraries locali e submodule;
- integrazioni con API/risorse esterne;
- componenti di validazione/rendering;
- export e trasformazioni in piu' formati.

Questo livello di ampiezza non e' compatibile con il principio guida del repository:

1. cambi incrementali;
2. una milestone/PR per volta;
3. compatibilita' prima del refactor esteso;
4. codice, test e documentazione sempre allineati.

---

## 2) Posizionamento rispetto al repository

### 2.1 Fit con il repo

Il repository `mcp-servers` e' centrato su:

- server MCP;
- skill portabili;
- disciplina architetturale e di compatibilita';
- workflow controllati e progressivi;
- confini chiari tra intake, orchestrazione e specializzazione.

Il progetto SVG puo' essere coerente con questo assetto **solo se introdotto a piccoli blocchi**, evitando di trasformare il repository in una piattaforma generalista di asset creativi.

### 2.2 Principio guida per questa iniziativa

Il repository puo' ospitare:

- skill SVG;
- documentazione di workflow;
- eventuali integrazioni MCP utili alla validazione/rendering;
- tooling minimo giustificato da use case concreti.

Il repository **non deve automaticamente assumere** come perimetro stabile:

- grandi collezioni di asset creativi locali;
- submodule grafici multipli senza evidenza di reale ritorno;
- dipendenze pesanti o difficili da portare cross-host;
- automazioni che richiedono policy di installazione invasive o poco controllabili.

---

## 3) Strategia di sviluppo

### 3.1 Branching model

L'iniziativa deve vivere inizialmente su un branch dedicato, ad esempio:

- `feature/svg-framework`
- oppure `incubator/svg-framework`

All'interno del branch dedicato, il lavoro deve essere organizzato per fasi piccole e verificabili.

### 3.2 Regola di promozione verso master

Una fase puo' essere promossa verso `master` solo se soddisfa tutti i requisiti seguenti:

1. perimetro limitato e chiaramente documentato;
2. dipendenze motivate e sostenibili;
3. compatibilita' con i principi del repo;
4. smoke/eval/test minimi presenti;
5. documentazione aggiornata;
6. assenza di allargamenti di scope non approvati;
7. valore autonomo anche senza completamento delle fasi successive.

### 3.3 Regola di non-accumulo

Il branch dedicato non deve diventare un contenitore indistinto di:

- RFC;
- submodule;
- skill;
- script;
- prove locali;
- tooling non ancora governato.

Ogni avanzamento deve essere riconducibile a una fase specifica, con output distinguibile e decisione esplicita: **promuovere**, **rinviare**, **scartare**.

---

## 4) Boundary permanenti

### 4.1 Cosa questa roadmap vuole ottenere

- introdurre capacita' SVG utili e realistiche;
- partire da skill a basso rischio e alto riuso;
- rendere il lavoro verificabile e manutenibile;
- evitare un'integrazione monolitica e fragile.

### 4.2 Cosa questa roadmap non assume come garantito

Non si assume fin dall'inizio che debbano entrare nel repo:

- submodule di librerie SVG;
- indice asset locale `skills/svg/assets/index.json`;
- workflow completi di composizione illustrativa;
- conversioni raster avanzate;
- export multi-formato;
- tooling pesante lato host;
- integrazioni con servizi remoti come dipendenza strutturale.

Questi elementi potranno essere introdotti solo in fasi successive, se giustificati da evidenze raccolte nelle fasi precedenti.

---

## 5) Fasi del progetto

## Fase 0 - Formalizzazione e governance del progetto

### Scopo
Trasformare la proposta architetturale in un progetto governabile, con confini, decisioni e criteri di promozione espliciti.

### Deliverable
- questo documento di roadmap;
- riallineamento dello stato di `docs/svg/svg-framework-analysis.md` come documento architetturale di riferimento;
- definizione del branch dedicato;
- definizione dei criteri di promozione e dei boundary permanenti.

### Esito atteso
Chiarezza sul fatto che SVG Framework non e' una milestone unica, ma un programma di lavoro incubato.

### Fuori scope
- implementazione tecnica di skill;
- aggiunta di dipendenze;
- introduzione di asset library.

---

## Fase 1 - Core SVG minimo e integrabile

### Scopo
Introdurre il nucleo SVG piu' coerente con il repository, con rischio contenuto e utilita' autonoma.

### Deliverable minimi
- `skills/svg/SKILL.md`
- `skills/svg/references/workflows/optimize.md`
- `skills/svg/references/workflows/validate.md`
- documentazione essenziale su eventuale uso di SVG-MCP
- smoke/eval minimi per routing e output

### Razionale
Questa fase consente di ottenere subito valore su SVG esistenti, senza introdurre l'intero framework.

### Criteri di accettazione
- skill triggerabili e con confini chiari;
- nessuna dipendenza pesante obbligatoria non giustificata;
- test/smoke minimi presenti;
- documentazione aggiornata;
- valore autonomo anche se il resto del framework non verra' mai realizzato.

### Linee operative documentali (allineamento criteri Fase 1)

Per mantenere la Fase 1 promuovibile verso `master`, la documentazione operativa deve esplicitare anche i seguenti punti.

#### Quando usare SVG-MCP in Fase 1
- usare SVG-MCP solo per task sul **core minimo** (ottimizzazione non distruttiva e validazione di SVG esistenti);
- preferirlo quando serve output verificabile, ripetibile e tracciabile su file gia' presenti;
- non usarlo per workflow fuori scope Fase 1 (asset libraries, raster -> SVG, export avanzati, pipeline illustration).

#### Prerequisiti minimi
- skill/documentazione locale `skills/svg/` disponibile e coerente con i confini Fase 1;
- input minimo disponibile (path `.svg` o blocco SVG inline completo);
- smoke test minimi di routing/output eseguiti per i casi coperti.

#### Fallback se il tool non e' disponibile
- non fallire in modo silenzioso: dichiarare esplicitamente indisponibilita' del tool/capability;
- fornire fallback operativo minimo: analisi statica del contenuto SVG disponibile + elenco limiti + prossimo passo consigliato;
- evitare di simulare esecuzioni non realmente supportate dall'host.

#### Policy dipendenze (leggere e opzionali)
- in Fase 1 le dipendenze devono restare **leggere, motivate e opzionali**;
- nessuna dipendenza pesante deve diventare requisito obbligatorio per usare optimize/validate;
- se una dipendenza opzionale non e' presente, il flusso deve degradare con messaggio esplicito e fallback documentato.

#### Nota operativa su runtime capability
- se in una fase successiva vengono introdotte nuove capability runtime lato server MCP, aggiungere una nota esplicita di riavvio server nelle istruzioni operative e nelle note di rilascio della modifica.

### Fuori scope
- asset libraries locali;
- workflow illustration;
- raster -> SVG;
- export avanzati;
- sprite/component generation;
- installazioni automatiche generalizzate.

### Promovibilita' verso master
**Alta**, se i deliverable sono puliti e testati.

---

## Fase 2 - Workflow su SVG esistenti

### Scopo
Estendere il core minimo con operazioni frequenti su SVG gia' disponibili, senza ancora introdurre grandi pacchetti di asset o pipeline complesse.

### Deliverable possibili
- palette / sostituzione colori;
- brand-kit minimale;
- conversione semplice in componente;
- ottimizzazioni aggiuntive di validazione o pulizia.

### Deliverable avviati nel branch incubatore
- `skills/svg/references/workflows/color-palette.md`
- `skills/svg/references/workflows/brand-kit.md`
- `skills/svg/references/workflows/to-component.md`
- aggiornamento router `skills/svg/SKILL.md` per routing Fase 2 su SVG esistenti
- estensione smoke/eval testuali in `skills/svg/evals/evals.json`

### Criteri di accettazione
- nessun allargamento improprio del perimetro;
- ogni nuova skill deve avere use case verificabile;
- output comprensibile e mantenibile;
- dipendenze contenute.

### Fuori scope
- submodule grafici;
- indice asset locale;
- composizione illustrazioni multi-sorgente.

### Promovibilita' verso master
**Media-alta**, se rimane focalizzata su SVG esistenti e non introduce peso strutturale.

### Stato implementazione (aggiornato al 2026-04-17)

Stato proposto: **chiudibile** (in branch incubatore), con evidenze locali di smoke.

Evidenze implementative presenti:

- workflow colore/componente presenti:
  - `skills/svg/references/workflows/color-palette.md`
  - `skills/svg/references/workflows/brand-kit.md`
  - `skills/svg/references/workflows/to-component.md`
- routing skill aggiornato su workflow Fase 2 in `skills/svg/SKILL.md`;
- eval estesi in `skills/svg/evals/evals.json`;
- smoke automatico locale introdotto: `scripts/check-svg-skill-smoke.js --profile phase2` (alias compatibile: `scripts/smoke-svg-phase2.js`) con verifica:
  - mapping colore non distruttivo;
  - preservazione `currentColor`;
  - baseline `brand-kit` (`role`, `title`, `aria-labelledby`);
  - conversione `to-component` con props minime (`size`, `color`, `className`);
- fixture dedicate disponibili:
  - `skills/svg/evals/fixtures/valid-minimal.svg`
  - `skills/svg/evals/fixtures/invalid-malformed.svg`
  - `skills/svg/evals/fixtures/valid-currentcolor.svg`

Checklist rapida chiusura Fase 2:

1. scope rispettato (solo SVG esistenti, nessun submodule/asset index): **OK**
2. use case verificabili per skill nuove: **OK**
3. output mantenibile e comprensibile (workflow + output attesi): **OK**
4. dipendenze contenute (nessuna dipendenza pesante aggiunta): **OK**

---

## Fase 3 - Tooling di conversione e trasformazione (MVP)

### Scopo
Introdurre in modo controllato un MVP di workflow che richiedono tool CLI esterni, mantenendo fallback espliciti e compatibilita' legacy.

Analisi tecnica di dettaglio (librerie, integrazione, submodule/fallback):

- `docs/svg/svg-framework-phase3-tooling-analysis.md`

### Deliverable possibili
- `skills/svg/references/workflows/from-raster.md`
- export basilare verso PNG/PDF
- policy operativa chiara per disponibilita' tool e fallback
- checker capability runtime: `scripts/check-svg-tooling.js`
- smoke dedicato Fase 3: `scripts/smoke-svg-phase3.js`

### Funzioni da introdurre ora (Fase 3)

Per allineare la roadmap con l'analisi `docs/svg/svg-skill-node-scripts-analysis.md`,
in Fase 3 vanno introdotte solo funzioni computazionali deterministiche, locali e
con perimetro stretto, senza anticipare scope di Fase 4/5.

Priorita' alta (pilot consigliato):

- `superellipse` / supercerchio parametrico (primo candidato)
- punti su arco/circonferenza (`arc-points`, `polar-distribute`)
- helper geometrici piccoli (`bezier-handles`, `fit-viewbox`, `rounded-corners`)

Vincoli obbligatori per l'introduzione in Fase 3:

- zero dipendenze esterne oppure razionale forte e documentato;
- contratto CLI minimale e output machine-readable;
- almeno 2 smoke test (happy-path + invalid input);
- fallback esplicito quando lo script non e' disponibile.

Nota di scope:

- queste funzioni restano helper della skill SVG (control plane nella skill,
  execution helper nello script);
- non devono diventare orchestrazione generale o pipeline illustrativa.

### Governance `SKILL.md` e catalogo helper

Per sviluppi futuri della skill SVG, mantenere il router principale snello e
spostare i dettagli operativi in reference locali. La guida operativa e':

- `docs/svg/svg-skill-maintenance-guide.md`

Regole sintetiche:

- `skills/svg/SKILL.md` espone scope, routing e link alle reference;
- `skills/svg/references/` contiene runbook riusabili e host-specific;
- `skills/svg/tools/catalog.json` e' la discovery machine-readable degli helper;
- ogni nuovo helper deve aggiornare catalogo, README tool, smoke e, se cambia il
  comportamento skill-level, anche eval.

### Policy MVP Fase 3 (allineamento operativo)

- routing skill Fase 3 atteso nel perimetro `skills/svg/`:
  - `from-raster`
  - `export/to-png-batch`
  - `export/to-pdf`
- policy Windows: export PNG/PDF solo **inkscape** (`rsvg-convert` non supportato su Windows);
- policy raster MVP:
  - default colore: `vtracer`
  - fallback specialistico B/N: `potrace`
  - fallback finale: `inkscape`
- nessun fail silenzioso: in assenza tool, errore esplicito con fallback e prossimo passo operativo.

### Rischi principali
- dipendenze pesanti;
- differenze Linux/macOS;
- supporto host non uniforme;
- aumento del costo di onboarding.

### Criteri di accettazione
- ogni dipendenza deve essere realmente necessaria;
- la policy di installazione deve essere chiara e non invasiva;
- le skill devono degradare in modo esplicito, non fallire silenziosamente;
- test e documentazione devono coprire i casi di assenza tool.
- checker/smoke Fase 3 eseguiti e coerenti con la policy host.

### Verifica operativa minima MVP

Eseguire:

```bash
node scripts/check-svg-tooling.js
node scripts/smoke-svg-phase3.js --profile no-tools
node scripts/smoke-svg-phase3.js --profile tools-present
node scripts/smoke-svg-phase3.js --profile windows-inkscape-first
node scripts/smoke-svg-phase3.js --profile linux-rsvg-first
```

Attesi minimi:

- output capability machine-readable con `tools`, `selected`, `fallbacks`, `warnings`;
- fallback espliciti in ogni profilo;
- rispetto policy Windows inkscape-only per export PNG/PDF.

### Nota operativa runtime capability

Se in una fase successiva viene modificato codice runtime capability lato server MCP, aggiungere nota di riavvio server nelle istruzioni operative e nelle note di rilascio.

### Promovibilita' verso master
**Media**, solo se la superficie operativa resta ben controllata.

---

## Fase 4 - Asset libraries locali e indicizzazione

### Scopo
Valutare se esiste un ritorno sufficiente a giustificare l'introduzione di librerie SVG locali nel repository o tramite submodule.

### Deliverable possibili
- eventuale struttura `assets/`
- eventuale script di indexing
- documentazione licenze e policy aggiornamento
- decisione esplicita su submodule vs alternative leggere

### Funzioni piu' consone alla Fase 4

Le funzioni da collocare in Fase 4 sono quelle legate a discovery e governance
degli asset, non alla generazione illustrativa completa:

- build/check indice locale (`build-svg-asset-index`, `check-svg-asset-index`);
- normalizzazione metadati per ricerca (`name`, `keywords`, `library_id`);
- validazione path, licenza e consistenza submodule.

Funzioni da non anticipare in Fase 3:

- retrieval avanzato multi-libreria con ranking sofisticato;
- composizione automatica di scene a partire da asset eterogenei;
- pipeline che dipendono da cataloghi estesi non ancora governati.

### Rischi principali
- peso del repo;
- manutenzione;
- drift dei path;
- costo di aggiornamento;
- allargamento del repository oltre il suo nucleo.

### Criteri di accettazione
- evidenza concreta che le fasi precedenti non bastano;
- licenze e manutenzione chiarite;
- automazione minima per evitare degrado operativo;
- impatto sul repo accettabile.

### Stato implementazione (aggiornato al 2026-04-27)

Stato: **Fase 4 Chiusa**.

Evidenze:
- Indice `skills/svg/assets/index.json` valido con 1937 asset (Lucide, Open Peeps).
- Tooling `search-assets.js` verificato e integrato.
- Licenze documentate in `skills/svg/assets/licenses/` (ISC, CC0).
- Smoke test `scripts/smoke-svg-phase4.js` superato (ok).
- Router `skills/svg/SKILL.md` aggiornato con gateway per Fase 5.

Verifica locale rieseguita al 2026-04-27:

```bash
node scripts/check-svg-asset-index.js
node scripts/smoke-svg-phase4.js --profile pilot-present
node scripts/smoke-svg-phase4.js --profile license-metadata
node scripts/smoke-svg-phase4.js --profile asset-search
node scripts/smoke-svg-phase4.js --profile missing-assets
```

Esito:

- indice valido: 2 librerie, 1937 asset;
- librerie pilot presenti e path indicizzati esistenti;
- metadati licenza presenti per `lucide` e `open-peeps`;
- ricerca asset agent-facing funzionante;
- fallback `missing-assets-root` esplicito e non silenzioso.

### Promovibilita' verso master
**Media-Alta**, la base asset è stabile e governata.

---

## Fase 5 - Workflow illustrativo completo

### Scopo
Realizzare, solo se giustificato da evidenze raccolte nelle fasi precedenti, un
workflow strutturato di ricerca, selezione, composizione e refine per
illustrazioni SVG.

Questa fase non deve trasformare la skill SVG in un generatore creativo
generalista. Il suo perimetro corretto e' un workflow tecnico e governato che
riusa asset indicizzati, regole di composizione esplicite e validazioni
ripetibili per produrre illustrazioni leggere, coerenti e verificabili.

### Deliverable possibili
- `skills/svg/illustration/`
- workflow search -> select -> compose -> refine
- uso eventuale di librerie locali o remote
- regole di coerenza stilistica
- validazione visiva strutturata

### Stato decisionale preliminare

Stato proposto: **avviabile solo come valutazione/pilot ristretto**, non come
implementazione piena.

La chiusura formale di Fase 4 rimuove il prerequisito tecnico principale:
asset locali controllati (`lucide` e `open-peeps`), indice locale, licenze e
ricerca deterministica sono disponibili e verificati. Questo abilita la
valutazione concreta di Fase 5, ma non basta da solo a giustificarne il rollout.
La differenza architetturale resta netta:

- Fase 4 risponde a "trovare asset";
- Fase 5 risponde a "comporre una scena con asset";
- la seconda introduce scelte semantiche, layout, layering, proporzioni, palette,
  validazione visiva e rischio di output soggettivo.

Di conseguenza Fase 5 deve partire, se parte, come **pilot ristretto** e non come
rollout del framework completo immaginato nell'analisi architetturale originaria.

Impatto della chiusura Fase 4:

- prerequisito asset/index/licenze: **soddisfatto**;
- prerequisito valore non coperto dalle fasi precedenti: **da dimostrare**;
- prerequisito QA visiva per composizioni: **da definire nel pilot**;
- prerequisito casi d'uso reali approvati: **da raccogliere prima
  dell'implementazione**.

### Prerequisiti obbligatori

Prima di aprire Fase 5 devono essere soddisfatti questi prerequisiti:

1. Fase 4 chiusa o dichiarata stabile per il pilot (**OK al 2026-04-27**):
   - `skills/svg/assets/index.json` generabile e validabile;
   - `skills/svg/tools/search-assets.js` funzionante su `icons` e
     `illustrations`;
   - licenze e attribution documentate per ogni libreria usata;
   - policy update delle librerie chiara.
2. Boundary della skill SVG aggiornati senza ambiguita':
   - asset discovery resta riuso locale;
   - composizione multi-asset resta fuori scope finche' non esiste
     `skills/svg/illustration/`;
   - il router non deve mandare richieste creative generiche alla pipeline Fase 5.
3. QA visiva disponibile:
   - render browser o export PNG verificabile;
   - screenshot o evidenza equivalente;
   - fallback esplicito se Playwright/rendering non e' disponibile.
4. Set minimo di casi d'uso approvati:
   - almeno 3 casi reali interni dove `create-simple-svg` + asset discovery +
     brand-kit non bastano;
   - brief con vincoli misurabili: formato, palette, destinazione, librerie
     ammesse, livello di complessita'.

Nota: con Fase 4 chiusa, l'elemento bloccante non e' piu' la disponibilita'
degli asset, ma la prova che una pipeline compositiva aggiunga valore reale
senza spostare il repo verso una piattaforma creativa generalista.

### Criterio sintetico di avvio

Fase 5 puo' partire solo se esistono casi reali non coperti da Fase 1-4 e se il
pilot resta locale, deterministico e verificabile: asset gia' governati, preset
di layout espliciti, nessuna nuova libreria, nessuna dipendenza remota
obbligatoria e QA visiva prevista.

### Perimetro del pilot Fase 5

Il pilot deve essere volutamente piccolo.

Scope consigliato:

- una sola famiglia stilistica primaria per pilot: `open-peeps`;
- uso di `lucide` solo come elementi secondari, se lo stile resta compatibile;
- massimo 3 asset compositivi per scena nella prima iterazione;
- layout predefiniti, non posizionamento libero;
- output singolo SVG standalone;
- palette brand opzionale ma vincolata a mapping esplicito;
- nessun fetch remoto obbligatorio;
- nessuna generazione raster;
- nessuna animazione;
- nessun export multi-formato oltre quanto gia' coperto da Fase 3.

Fuori scope del pilot:

- scene narrative complesse;
- composizione da librerie eterogenee non governate;
- ricerca web/API remota come dipendenza strutturale;
- generazione di asset nuovi per colmare buchi semantici;
- editor visuale;
- scoring estetico opaco;
- modifica massiva o normalizzazione completa degli asset upstream.

### Architettura proposta

La struttura massima ammissibile per il pilot e':

```text
skills/svg/illustration/
├── SKILL.md
├── search.md
├── select.md
├── compose.md
├── refine.md
└── layout-presets.md
```

Questi file devono restare workflow documentali e procedurali. Gli helper
computazionali vanno aggiunti solo se deterministici e piccoli, preferibilmente
in `skills/svg/tools/`, aggiornando `tools/catalog.json`, README, smoke ed eval.

Responsabilita' consigliate:

- `SKILL.md`: router interno del workflow, input richiesto, limiti, fallback;
- `search.md`: uso esclusivo dell'indice locale e di `search-assets.js` nel
  pilot;
- `select.md`: criteri di compatibilita' tra asset, libreria, pose, tema e
  palette;
- `compose.md`: template layout a zone e regole di scala/layering;
- `refine.md`: applicazione palette, accessibilita', optimize, validate e QA
  visiva;
- `layout-presets.md`: preset ammessi (`empty-state`, `login-panel`,
  `dashboard-placeholder`, `profile-card`) con dimensioni e zone dichiarate.

### Contratto input/output del workflow

Input minimo consigliato:

```json
{
  "purpose": "login-illustration",
  "format": { "width": 640, "height": 480 },
  "style": "open-peeps-flat",
  "palette": {
    "primary": "#2563eb",
    "secondary": "#14b8a6",
    "neutral": "#111827",
    "background": "#f8fafc"
  },
  "allowed_libraries": ["open-peeps", "lucide"],
  "layout_preset": "login-panel",
  "max_assets": 3,
  "accessibility_title": "Illustrazione login applicazione"
}
```

Output minimo consigliato:

```json
{
  "status": "ok|partial|blocked",
  "output_svg": "path/to/output.svg",
  "layout_preset": "login-panel",
  "assets_used": [
    {
      "library": "open-peeps",
      "path": "skills/svg/assets/libraries/open-peeps/svg/...",
      "license": "CC0",
      "attribution": "not-required"
    }
  ],
  "validation": {
    "structural": "pass|fail",
    "visual": "pass|fail|not-run",
    "warnings": []
  },
  "fallbacks": []
}
```

Il contratto deve evitare input liberi come "fammi una bella illustrazione" senza
vincoli. Se il brief e' insufficiente, il workflow deve chiedere chiarimento o
degradare a proposta di asset singolo/adattamento semplice.

### Strategia search -> select -> compose -> refine

**Search**

- usare prima `skills/svg/tools/search-assets.js`;
- limitare risultati per `kind=illustrations` e libreria ammessa;
- includere solo asset con `exists: true`;
- conservare query, candidati e score come evidenza.

**Select**

- preferire coerenza a varieta';
- non mescolare stili incompatibili;
- limitare asset secondari a elementi che non competono con il soggetto;
- scartare asset con viewBox o struttura non gestibile senza trasformazioni
  rischiose.

**Compose**

- usare preset a zone (`background`, `midground`, `foreground`);
- applicare scale e transform deterministici;
- mantenere ogni asset in `<g id="...">` tracciabile;
- evitare trasformazioni distruttive su path complessi se non necessarie;
- non fare collage libero di molti asset.

**Refine**

- applicare palette con mapping documentato;
- aggiungere `title`, `desc`, `role="img"` e `aria-labelledby` se output
  standalone;
- eseguire optimize/validate secondo workflow gia' presenti;
- fare QA visiva e riportare evidenza;
- se QA fallisce, iterare una volta su layout/refine prima di dichiarare
  `partial` o `blocked`.

### Funzioni piu' consone alla Fase 5

Le funzioni candidate alla Fase 5 sono quelle ad alta complessita' compositiva
e a maggiore variabilita' semantica:

- orchestrazione illustrativa multi-step (`search -> select -> compose -> refine`);
- regole di coerenza tra asset, stile, proporzioni e layering;
- helper di layout/composizione che dipendono da asset libraries reali;
- normalizzazione leggera di asset selezionati, solo quando necessaria alla
  composizione;
- generazione di manifest dell'illustrazione prodotta.

Queste funzioni entrano solo dopo evidenza che Fase 1-4 non coprono il bisogno
e dopo validazione forte di manutenzione/costo operativo.

Funzioni da non includere in Fase 5:

- motore creativo generico;
- ranking semantico remoto obbligatorio;
- ingest di nuove librerie;
- editor WYSIWYG;
- conversione raster;
- animazione;
- export avanzato;
- dipendenze pesanti non gia' motivate da Fase 3.

### Test, smoke ed eval minimi

Il pilot Fase 5 deve aggiungere verifiche testuali e operative, senza dipendere
da giudizi estetici non ripetibili.

Smoke minimi consigliati:

```bash
node scripts/smoke-svg-phase5.js --profile no-assets
node scripts/smoke-svg-phase5.js --profile search-select
node scripts/smoke-svg-phase5.js --profile compose-open-peeps
node scripts/smoke-svg-phase5.js --profile visual-qa-fallback
```

Attesi minimi:

- `no-assets`: errore esplicito, nessun fail silenzioso;
- `search-select`: candidati ordinati e asset esistenti;
- `compose-open-peeps`: SVG output con gruppi asset tracciabili;
- `visual-qa-fallback`: stato `visual: not-run` motivato se rendering non
  disponibile.

Eval minimi:

- prompt che deve attivare Fase 5;
- prompt che deve restare in asset discovery Fase 4;
- prompt creativo troppo ampio che deve essere rifiutato/degradato;
- prompt con libreria mancante che deve tornare a gate Fase 4;
- prompt con richiesta di scena complessa che deve produrre limite esplicito.

### Rischi principali

- complessita' elevata;
- dipendenza da asset/servizi esterni;
- output meno prevedibili;
- scostamento dal focus originario del repo.
- ambiguita' tra generazione creativa e trasformazione tecnica;
- crescita incontrollata di librerie e metadata;
- QA visiva costosa o non uniforme tra host;
- rischio di asset composti validi sintatticamente ma scadenti o incoerenti.

### Mitigazioni

- partire solo con asset locali gia' governati;
- usare layout preset invece di composizione libera;
- mantenere massimo asset basso nel pilot;
- richiedere manifest dell'output con asset/licenze/fallback;
- bloccare nuove librerie tramite gate Fase 4;
- rendere QA visiva parte della definizione di done;
- promuovere solo sottocomponenti autonomi, non l'intera pipeline in blocco.

### Criteri di accettazione
- dimostrazione di valore reale non ottenibile con le fasi precedenti;
- confini molto chiari;
- manutenzione sostenibile;
- rischio architetturale giudicato accettabile.
- nessuna regressione dei workflow Fase 1-4;
- routing skill aggiornato senza intercettare richieste creative generiche;
- documentazione `skills/svg/illustration/` completa ma sintetica;
- smoke/eval Fase 5 presenti;
- output di esempio con manifest e QA visiva;
- licenze/attribution riportate per ogni asset riusato;
- fallback espliciti per asset mancanti, tool mancanti e QA visiva non
  disponibile.

### Done minimo per pilot

Il pilot Fase 5 e' chiudibile solo quando:

1. esiste una cartella `skills/svg/illustration/` con router e workflow
   documentali minimi;
2. il workflow usa solo asset Fase 4 gia' indicizzati;
3. almeno un preset produce un SVG standalone valido;
4. lo smoke dedicato copre asset mancanti, search/select, compose e fallback QA;
5. il router principale `skills/svg/SKILL.md` mantiene chiaro il limite tra
   asset discovery, SVG semplice e composizione illustrativa;
6. la roadmap e l'analisi architetturale non si contraddicono;
7. la promozione verso `master` puo' essere limitata a pezzi autonomi.

### Promovibilita' verso master
**Bassa di default**.
Da promuovere solo in blocchi selezionati e dopo validazione forte.

Blocchi potenzialmente promuovibili singolarmente:

- documentazione `skills/svg/illustration/` se non abilita comportamento
  rischioso nel router;
- preset layout statici;
- manifest output;
- smoke/eval di routing;
- helper deterministici piccoli.

Blocchi da non promuovere finche' non maturi:

- orchestrazione automatica completa;
- dipendenze remote;
- nuove librerie asset;
- scoring estetico complesso;
- composizione multi-libreria libera.

---

## 6) Ordine di priorita' raccomandato

Ordine consigliato di avanzamento:

1. Fase 0 - governance e formalizzazione
2. Fase 1 - core SVG minimo
3. Fase 2 - workflow su SVG esistenti
4. Fase 3 - conversioni e tooling esterno
5. Fase 4 - asset libraries e indicizzazione
6. Fase 5 - workflow illustrativo completo

Il criterio guida e':

- prima cio' che e' utile, piccolo e promuovibile;
- poi cio' che e' utile ma piu' costoso;
- infine cio' che allarga davvero il perimetro del repository.

### Matrice sintetica funzioni -> fase

- Fase 3 (ora): primitive matematiche/geometriche deterministiche e testabili.
- Fase 4 (dopo pilot): funzioni di indicizzazione, discovery locale e governance licenze.
- Fase 5 (solo se giustificata): composizione illustrativa completa e regole stilistiche avanzate.

---

## 7) Criteri trasversali di qualita'

Per ogni fase, prima della promozione verso `master`, devono essere verificati almeno i seguenti punti:

1. **Scope chiaro**
   La fase deve dichiarare cosa introduce e cosa lascia fuori.

2. **Compatibilita' con il repo**
   Nessun refactor monolitico o ampliamento non governato.

3. **Test e smoke minimi**
   Il comportamento deve essere verificabile.

4. **Documentazione coerente**
   I file guida devono essere aggiornati e non contraddirsi.

5. **Dipendenze sotto controllo**
   Nessuna dipendenza nuova senza razionale e istruzioni chiare.

6. **Valore autonomo**
   La fase deve avere senso anche da sola.

7. **Promovibilita' reale**
   Deve essere possibile immaginare il merge in `master` senza trascinare con forza il resto del programma.

---

## 8) Gestione documentale

### 8.1 Documento architetturale di riferimento

Resta:

- `docs/svg/svg-framework-analysis.md`

Ruolo:
- RFC / analisi architetturale;
- catalogo di possibilita', use case, skill e tooling;
- base concettuale da cui derivare il lavoro operativo.

### 8.2 Documento operativo attivo

Diventa:

- `docs/svg/svg-framework-roadmap.md`
- `docs/svg/svg-framework-phase4-asset-indexing-evaluation.md` (valutazione pre-implementazione Fase 4)
- `docs/svg/svg-framework-phase4-pilot-libraries.md` (baseline librerie pilot Fase 4)

Ruolo:
- roadmap viva del progetto;
- fonte di verita' sul piano multi-fase;
- riferimento per decisioni di scope, promozione e integrazione.

### 8.3 Regola di sincronizzazione

Se la roadmap evolve e una parte dell'analisi originaria non e' piu' valida, si deve:

- aggiornare l'analisi se il cambiamento e' concettuale;
- aggiornare la roadmap se il cambiamento e' operativo;
- evitare che il documento architetturale venga usato come backlog esecutivo.

---

## 9) Decisione finale

L'iniziativa SVG Framework viene approvata come:

- **programma multi-fase incubato**
- su **branch dedicato**
- con **promozione incrementale** verso `master`
- e con `docs/svg/svg-framework-analysis.md` mantenuto come riferimento architetturale, non come milestone esecutiva autonoma.

La prima fase con alta probabilita' di integrazione nel ramo principale e':

- **Fase 1 - Core SVG minimo e integrabile**

Le fasi successive restano subordinate ai risultati concreti delle fasi precedenti.

---

## 10) Prossimo passo operativo

Il prossimo passo raccomandato, dopo la chiusura formale di Fase 4, e':

1. mantenere `docs/svg/svg-framework-analysis.md` come base architetturale, non
   come backlog esecutivo;
2. usare questa roadmap come fonte operativa aggiornata;
3. raccogliere almeno 3 casi d'uso reali che richiedono composizione
   illustrativa e non sono coperti da Fase 1-4;
4. se il criterio sintetico Fase 5 e' soddisfatto, aprire solo un pilot documentale/operativo
   ristretto su `open-peeps` + indice locale, senza nuove librerie e senza
   dipendenze remote obbligatorie.