# Legacy Modernization Workflow

Usa questo riferimento quando l'obiettivo richiede una modernizzazione o un replatforming end-to-end di un sistema legacy verso un nuovo stack, con fasi dipendenti di discovery, contratti, implementazione, validazione e consegna.

Il workflow è agnostico rispetto a linguaggio, framework, runtime e paradigma sia del source sia del target. Selezionare le skill specialistiche solo dopo inventory e contratti condivisi, in base alle tecnologie effettivamente osservate.

Non usarlo per:

- solo inventory o ricostruzione del comportamento: usare `mcp-technical-analyst`;
- una singola modifica nel target: usare la skill specialistica;
- sola review di un diff/branch/PR: usare `mcp-code-reviewer`;
- migrazione CFML tra versioni o branch dello stesso prodotto tramite directory neutrale: usare `mcp-coldfusion-developer` in Cross-Version Migration Mode.

## Preflight bloccante

Prima di iniziare, verificare:

1. `source_project_path` assoluto e read-only;
2. repository sorgente e branch;
3. `target_project_path` assoluto e distinto dal source;
4. repository target e branch;
5. commit/ref se serve una baseline puntuale;
6. `evidence_save_path` assoluto;
7. eventuale `neutral_path` disposable;
8. ticket, requisito o documento funzionale;
9. obiettivo: rewrite, replatforming, strangler migration, sostituzione backend, estrazione modulo o equivalente;
10. criterio di compatibilità:
    - comportamento identico;
    - miglioramenti consentiti;
    - bug legacy da preservare o correggere;
11. ambienti disponibili;
12. mapping progetto → `.env` → DB → ambiente;
13. classificazione dei dati e presenza di segreti/PII;
14. vincoli di cutover, rollback e downtime.

Non ricavare source o target dal `cwd`. Non leggere configurazioni di dominio dal repository MCP. Non inventare input mancanti. Fermarsi se una scelta cambia materialmente il deliverable.

Gli alias logici `source_project_path`/`target_project_path` si passano ai tool tramite `project_path`; `evidence_save_path`/`neutral_path` tramite `save_path`. Non introdurre nuovi campi schema MCP.

## Routing delle fasi

| Fase | Owner primario | Sidecar |
|---|---|---|
| Discovery e source recovery | `mcp-technical-analyst` | skill sorgente, git/docs |
| Inventory e parity contract | `mcp-technical-analyst` | DB/docs, massimo 2 scout read-only |
| Strategia e gate umano | `mcp-master-orchestrator` | technical analyst |
| Contratti e scaffold | skill target / `implementer` | database se necessario |
| Implementazione | skill target / `implementer` | nessuno o un sidecar stretto |
| Integrazione | un solo integration owner | skill target |
| Spec compliance e review | `mcp-code-reviewer` | skill dominio |
| Verifica funzionale | tool/test pertinenti | `mcp-browser-automation` solo se serve |
| Cutover e rollback | orchestrator + owner tecnico | DB/browser/ops secondo impatto |
| Handoff e documentazione | `mcp-handoff-pack` | `mcp-docs-navigator` se richiesto |

## Limiti di parallelismo

Applicare i limiti canonici:

- discovery: massimo 2 scout read-only;
- implementazione: massimo 1 implementer attivo sullo stesso `project_path`;
- validazione/report: massimo 2 attività parallele dopo il freeze;
- profondità handoff: massimo 2 livelli oltre l'orchestrator.

Non avviare implementer paralleli nello stesso checkout anche se i file sembrano disgiunti.

## Fase 1 — Discovery e source recovery

Delegare a `mcp-technical-analyst`.

Obiettivi:

- leggere `AGENTS.md`, eventuali `RULES.md` e documentazione locale;
- verificare `source_project_path`, `target_project_path` ed `evidence_save_path`;
- congelare source e target baseline;
- mantenere il source read-only e il target come unico checkout write-capable;
- cercare copie leggibili, backup, versioni precedenti e history;
- ricorrere a source recovery soltanto se non esiste una fonte leggibile;
- registrare provenienza e checksum di artefatti derivati;
- non eseguire payload legacy.

Output minimo:

- scope sorgente;
- fonti consultate;
- evidenze osservate;
- artefatti derivati;
- limiti e punti aperti.

## Fase 2 — Inventory e parity contract

Delegare a `mcp-technical-analyst`.

Suddividere l'esplorazione per dominio funzionale, non per numero di file.

Per ogni comportamento registrare:

- identificativo;
- dominio;
- fonte e ref;
- input e precondizioni;
- logica osservata;
- query o accessi dati con segreti redatti;
- output e status;
- side effect;
- caller;
- edge case;
- anomalia o bug sospetto;
- decisione: preservare, correggere, chiarire;
- proposta target;
- evidenza.

Un solo owner assembla il documento finale. Gli scout restituiscono testo strutturato e non modificano lo stesso artifact.

## Fase 3 — Strategia e gate umano

Definire una delle strategie:

- strangler/incrementale;
- sostituzione per modulo;
- parallel run;
- adapter/anti-corruption layer;
- big bang soltanto se motivato.

Prima dell'implementazione richiedere decisione umana per:

- bug legacy da correggere o preservare;
- cambi irreversibili;
- sicurezza/compliance;
- schema o dati;
- API incompatibili;
- cutover;
- dismissione del legacy.

Non trasformare inferenze in requisiti.

## Fase 4 — Contratti condivisi

Un solo implementer o owner tecnico definisce:

- DTO;
- API;
- schema;
- error model;
- invarianti;
- feature flag;
- contract test minimi.

Non avviare implementazione estesa finché i contratti non sono reviewable.

## Fase 5 — Implementazione incrementale

Usare la skill specialistica del target.

Regole:

1. lavorare per slice funzionali piccole;
2. mantenere una ownership file esplicita;
3. usare massimo 1 implementer per `project_path`;
4. non toccare shared entry point fuori dalla fase di integrazione;
5. aggiungere test del comportamento inventariato;
6. dichiarare divergenze rispetto al parity contract;
7. evitare refactor fuori scope;
8. preservare compatibilità legacy salvo decisione esplicita.

## Fase 6 — Integrazione

Un solo integration owner gestisce:

- registrazioni;
- dependency injection;
- routing;
- configurazione;
- wiring;
- migrazioni schema/dati;
- feature flag;
- hook di rollback.

Non distribuire questa fase tra agenti paralleli.

## Fase 7 — Review e verifica

Eseguire:

1. `mcp-code-reviewer` in modalità `spec-compliance`;
2. review tecnica;
3. test automatici;
4. riconciliazione dati quando applicabile;
5. confronto legacy/nuovo su casi rappresentativi;
6. browser automation soltanto se UI/runtime sono necessari.

Classificare ogni discrepanza:

| Stato | Significato |
|---|---|
| `MATCH` | comportamento equivalente |
| `INTENTIONAL_CHANGE` | differenza approvata |
| `LEGACY_BUG_PRESERVED` | anomalia mantenuta per compatibilità |
| `NEW_IMPLEMENTATION_BUG` | regressione da correggere |
| `UNCLEAR` | evidenza o requisito insufficiente |

## Verifica contro ambiente legacy

Preferire QA, staging o replica.

Su produzione consentire soltanto verifiche:

- autorizzate;
- read-only;
- idempotenti;
- senza notifiche, scritture o processi irreversibili;
- con rate limit;
- con dati di prova controllati;
- con segreti e PII redatti.

Documentare sempre ambiente e livello di conclusività.

## Fase 8 — Cutover e rollback

Preparare:

- piano rollout;
- feature flag o traffico progressivo;
- backup;
- migrazioni dati;
- metriche e log comparabili;
- soglie rollback;
- prova del rollback;
- ownership post-rilascio;
- finestra di monitoraggio;
- criterio di dismissione del legacy.

Fermarsi per review umana se rollback o ripristino dati non sono verificabili.

## Fase 9 — Documentazione e handoff

Produrre progressivamente:

- inventory;
- parity matrix;
- decision log;
- setup/config guide;
- validation report;
- cutover/rollback plan.

Generare la reference API finale dal codice consegnato e segnalare divergenze rispetto ai documenti iniziali.

Chiudere con `mcp-handoff-pack`. Indicizzare con `mcp-docs-navigator` soltanto se richiesto.

## Stop conditions

Fermarsi o rieseguire il triage quando:

- sorgente o target non sono identificabili;
- requisito e comportamento legacy sono in conflitto;
- una decisione richiede accettazione di bug legacy;
- i contratti condivisi non sono stabili;
- il lavoro richiede più di un implementer nello stesso `project_path`;
- la verifica richiede side effect su produzione;
- rollback o ripristino dati non sono disponibili;
- emerge una migrazione CFML cross-version già coperta dalla skill specialistica.

## Evidenze minime di chiusura

- baseline source/target;
- inventory e parity matrix;
- decisioni umane;
- diff focalizzato;
- esito lint/test/smoke;
- classificazione discrepanze;
- piano cutover/rollback;
- rischi residui;
- handoff finale.