# Specifica implementativa self-contained — integrazione del workflow Legacy Modernization

Stato: **FINAL / Codex-ready**
Revisione: consolidata definitiva
Data: 2026-07-10
Ruolo applicativo: `mcp-technical-analyst`
Repository target: `sophiadeveloper/mcp-servers`
Branch target: `master`
Commit/ref target: non richiesto; specifica riferita al branch corrente
Fonte funzionale primaria: specifica v5 e sette finding della review conclusiva orientata al goal
Modalità prevista: implementazione locale tramite Codex, con patch incrementale e reviewable
Dipendenza dallo ZIP originario: **nessuna**
Compatibilità host del routing prompt: **Codex UserPromptSubmit**; nessuna equivalenza garantita su Antigravity
Fonti non accessibili: nessuna fonte obbligatoria

## Skill e riferimenti caricati

- `skills/mcp-technical-analyst/SKILL.md`
- `references/analysis-workflow.md`
- `references/ticket-first-light.md`
- `references/source-matrix.md`
- `references/deliverable-templates.md`
- `references/interactive-escalation.md`
- `references/functional-exploration.md`

---

## Correzioni incorporate nella specifica finale

Questa specifica consolida tutte le correzioni emerse nelle review precedenti e, in particolare, chiude in un'unica passata i sette finding conclusivi:

1. estende il routing analyst a source recovery, confronto legacy/nuovo, equivalenza e conflitto requisito/comportamento;
2. separa azioni di modernizzazione da semplici citazioni nominali di `modernizzazione`, `replatforming` o `rewrite`;
3. limita l'estrazione degli anti-pattern alla sola sezione `## Anti-trigger`;
4. sostituisce la penalità numerica con un'esclusione deterministica delle skill non protette;
5. porta il catalogo routing allo schema `version: 2` e formalizza rigenerazione e compatibilità runtime;
6. estrae un motore puro e diagnosticabile per rendere verificabili intent, lock, suppression e anti-pattern;
7. assegna priorità predefinita `0` agli intent preesistenti, ordine stabile e regola di suppression strettamente superiore.

Restano inoltre incorporati:

- anti-trigger separati dalle escalation positive;
- alias source/target/evidence mappati a `project_path` e `save_path`;
- source recovery read-only per `mcp-technical-analyst`;
- priorità `CFML cross-version > modernization end-to-end > analysis-only`;
- smoke automatici sugli eval critici e sui falsi positivi;
- gestione del drift agenti;
- nessuna nuova skill, nessun nuovo agente e nessuna modifica agli schema MCP.

## 0. Contratto di utilizzo del documento

Questo file, con nome canonico `specifica-implementativa-legacy-modernization.md`, sostituisce integralmente lo ZIP `legacy-migration.zip` come input per l'implementazione.

Codex deve poter completare il lavoro disponendo soltanto di:

1. checkout del repository `sophiadeveloper/mcp-servers`;
2. branch `master`;
3. questo file Markdown.

Non chiedere lo ZIP originario e non assumerne la disponibilità.

Prima di modificare file:

1. leggere `AGENTS.md`;
2. leggere i documenti richiamati da `AGENTS.md`;
3. leggere eventuali `RULES.md` presenti nelle directory target;
4. leggere i file target elencati nella specifica;
5. registrare lo stato iniziale con `git status --short`;
6. verificare che struttura, path e convenzioni non siano cambiati rispetto alla baseline;
7. non sovrascrivere, ripristinare o inglobare modifiche utente preesistenti;
8. se un file target non esiste o presenta una struttura materialmente diversa, fermarsi e documentare il conflitto prima di inventare una collocazione alternativa.

### Baseline osservata durante l'analisi

| File | Blob SHA osservato |
|---|---|
| `AGENTS.md` | `5c092d46e2967008aed41febb5e61ef0e79138da` |
| `skills/mcp-technical-analyst/SKILL.md` | `65d1be16c86dff85323aa312671104606d277610` |
| `skills/mcp-technical-analyst/evals/evals.json` | `738d44f3caaa8ea2630d3c570e270f5fed08082a` |
| `skills/mcp-master-orchestrator/SKILL.md` | `a626855656366110b39d3de6df260e9d15781563` |
| `skills/mcp-master-orchestrator/references/workflows.md` | `d0ed6766a1bb09a2338f9954b8ccd087c955759f` |
| `skills/mcp-master-orchestrator/evals/evals.json` | `24f60b8a4274a384b1b29d8eb6f6ac734f3e34e6` |
| `skills/mcp-coldfusion-developer/SKILL.md` | `7e147080712d35945217e9d7dbb403171e12f725` |
| `skills/mcp-coldfusion-developer/references/cross-version-migration.md` | `0e2e9c151124b533b1cbd2104f63f5acb34f53a0` |
| `docs/mcp-skills-agents-development-guide.md` | `f49cfd0cfd2e85e6cb4c4e286bc58b788e2d09b1` |
| `docs/skill-governance-matrix.md` | `4cae4a995424eb07a3ff54dede39afdfe0316cda` |
| `docs/agents/canonical-subagents.yaml` | `875dbddedb28910ff3a32190b664de66507160ab` |
| `scripts/build-routing-catalog.mjs` | `75dee5f8aafa98268c99226b2a87c1221afbe3b3` |
| `scripts/hooks/sophia-user-prompt-submit.mjs` | `2eeffb04131c0bac23a63f432c55a35cfab98fc2` |
| `scripts/smoke-codex-hooks.js` | `59dedfd73325cc8ae886355af5a8f20a6c4a047f` |
| `scripts/install-user-runtime.js` | `1d77e9c0f36ba0d179fe8a1cc3a2ffe7dee8af8b` |

Gli SHA sono riferimenti di confronto, non precondizioni rigide. Se il branch è avanzato, applicare le modifiche alla struttura corrente preservando le intenzioni di questa specifica.

### Decisione esplicita sul branch `master` e sulla guida dichiarata attiva per `rework`

Il branch target resta `master` perché è stato indicato esplicitamente dall'utente.

La guida `docs/mcp-skills-agents-development-guide.md` presente su `master` dichiara di essere fonte di verità attiva per il branch `rework`, mentre `AGENTS.md` di `master` continua a richiamarla come governance locale.

Per questa attività:

- applicare la guida come governance del checkout `master`;
- non cambiare branch;
- non modificare la dichiarazione relativa a `rework`;
- non interpretare tale dichiarazione come autorizzazione a implementare su `rework`;
- riportare la discrepanza nel riepilogo finale come nota documentale non bloccante.


---

## 1. Obiettivo

Integrare nel repository un workflow riusabile per la **modernizzazione end-to-end di sistemi legacy**, senza introdurre una nuova skill autonoma.

Il workflow deve coprire:

1. individuazione della sorgente realmente leggibile;
2. ricostruzione del comportamento legacy;
3. inventory funzionale e matrice di parità;
4. definizione dei contratti condivisi;
5. implementazione incrementale sul nuovo stack;
6. integrazione;
7. review di conformità;
8. validazione empirica legacy/nuovo;
9. cutover, osservabilità e rollback;
10. documentazione e handoff.

La soluzione deve rispettare il routing canonico del repository:

- analisi multi-sorgente → `mcp-technical-analyst`;
- coordinamento multi-fase → `mcp-master-orchestrator`;
- implementazione mono-dominio → skill specialistica;
- review → `mcp-code-reviewer`;
- verifica browser → `mcp-browser-automation`, solo se necessaria;
- handoff → `mcp-handoff-pack`;
- migrazione CFML cross-version dello stesso prodotto → modalità già esistente di `mcp-coldfusion-developer`.

---

## 2. Decisione architetturale vincolante

### Da fare

Integrare il contenuto utile in due skill esistenti:

1. `mcp-master-orchestrator`
   - proprietario del workflow end-to-end;
   - coordina fasi, gate e handoff;
   - non svolge direttamente l'intake analitico.

2. `mcp-technical-analyst`
   - proprietario di source discovery, source recovery, inventory e parity analysis;
   - resta read-only;
   - non implementa la migrazione.

### Da non fare

Non creare:

- `skills/legacy-migration/`;
- `skills/mcp-legacy-migration/`;
- `skills/mcp-legacy-modernization/`;
- un nuovo MCP server;
- un nuovo profilo agente;
- una nuova policy di selezione modelli;
- un nuovo sistema di task tracking;
- una seconda modalità Provider/Consumer generalizzata.

Non modificare la modalità cross-version CFML esistente, salvo l'aggiunta di eventuali rimandi anti-overlap strettamente necessari.

---

## 2.1 Contratto dei path, alias logici e permessi

Il workflow deve distinguere esplicitamente i seguenti alias logici:

| Alias di workflow | Uso | Permessi | Parametro canonico dei tool |
|---|---|---|---|
| `mcp_repo_path` | Checkout `mcp-servers` che contiene skill e governance | Scrittura solo durante questa manutenzione | path operativo del checkout, non nuovo campo MCP |
| `source_project_path` | Checkout del sistema legacy | Read-only | `project_path` valorizzato con il source |
| `target_project_path` | Checkout del sistema destinazione | Write-capable solo nelle fasi implementative | `project_path` valorizzato con il target |
| `evidence_save_path` | Root per inventory, parity matrix, report e prove | Scrittura controllata | base per `save_path` assoluti |
| `neutral_path` | Artefatti temporanei o derivati | Disposable e isolato | path locale esplicito, solo se supportato dal tool o dalla skill |

Questi nomi sono **alias logici del workflow**, non nuovi parametri degli schema MCP.

Regole di mapping:

1. ogni chiamata al progetto sorgente usa il parametro canonico `project_path` valorizzato con `source_project_path`;
2. ogni chiamata al progetto target usa `project_path` valorizzato con `target_project_path`;
3. ogni artefatto riusabile usa un `save_path` assoluto collocato sotto `evidence_save_path`;
4. `neutral_path` non deve essere aggiunto agli schema dei tool: usarlo solo come directory locale isolata quando l'operazione lo consente;
5. non modificare input schema MCP per introdurre `source_project_path`, `target_project_path`, `evidence_save_path` o `neutral_path`.

Regole obbligatorie:

1. usare path assoluti;
2. non ricavare source o target dal `cwd`;
3. non leggere `.env` di dominio dal repository MCP;
4. associare esplicitamente ogni `.env`, DB e ambiente al relativo progetto;
5. non scrivere nel `source_project_path`;
6. non usare lo stesso path per source e target;
7. usare `evidence_save_path` come root degli artefatti analitici;
8. usare `neutral_path` per source recovery o trasformazioni temporanee;
9. redigere path sensibili nei deliverable esterni;
10. fermarsi se source e target non sono distinguibili in modo verificabile.

### Preflight runtime del workflow

Prima di una modernizzazione richiedere o ricavare:

- `source_project_path`;
- repository e branch sorgente;
- `target_project_path`;
- repository e branch target;
- commit/ref per baseline puntuali;
- `evidence_save_path`;
- eventuale `neutral_path`;
- ticket, requisito o documento funzionale;
- obiettivo della migrazione;
- ambienti disponibili;
- mapping progetto → `.env` → DB → ambiente;
- criteri di compatibilità;
- vincoli di cutover e rollback;
- classificazione dei dati sensibili.

Non procedere se manca un dato che cambia materialmente il deliverable.

---

## 3. Contenuto funzionale originario incorporato

Questa sezione contiene tutto ciò che deve essere preservato del materiale originario. Non serve consultare lo ZIP.

### 3.1 Sequenza concettuale originaria

Il materiale originario definiva questa sequenza:

1. trovare la sorgente reale;
2. costruire un inventory con ricerca parallela;
3. creare scaffolding e contratti condivisi;
4. implementare moduli indipendenti;
5. integrare in un solo punto;
6. verificare empiricamente;
7. confrontare il nuovo sistema con il legacy;
8. tracciare dipendenze;
9. documentare progressivamente;
10. parallelizzare soltanto a granularità utile.

Questi concetti devono essere mantenuti, ma riallineati alla governance del repository.

### 3.2 Principi da preservare

- Cercare copie leggibili, backup, versioni precedenti e history prima di deoffuscare.
- Suddividere l'inventory per dominio funzionale, non per numero arbitrario di file.
- Chiedere agli scout domande concrete e criteri di completamento espliciti.
- Far restituire agli scout risultati strutturati; un solo owner compone il documento finale.
- Registrare posizione sorgente, input, logica, query, output, caller, edge case e proposta target.
- Non correggere silenziosamente anomalie legacy.
- Distinguere:
  - comportamento da preservare;
  - bug legacy deliberatamente corretto;
  - regressione del nuovo sistema;
  - comportamento non chiarito.
- Definire contratti condivisi prima dell'implementazione.
- Mantenere un solo owner per wiring e integrazione.
- Verificare i comportamenti con prove reali e ambienti disposable, non con affermazioni “dovrebbe funzionare”.
- Confrontare legacy e nuovo con casi rappresentativi.
- Scrivere inventory e report durante il lavoro.
- Generare la reference API finale dal codice effettivamente consegnato, non soltanto dai documenti di design.
- Evitare micro-deleghe che costano più del lavoro inline.

### 3.3 Adattamenti obbligatori

Il materiale originario proponeva implementer paralleli su file disgiunti. Nel repository corrente tale regola deve essere sostituita da:

- massimo 2 scout read-only in parallelo;
- massimo 1 implementer attivo sullo stesso `project_path`;
- massimo 2 attività di validazione/report dopo il freeze delle modifiche;
- nessun parallelismo di scrittura nello stesso checkout;
- eventuale parallelismo futuro soltanto con worktree/workspace isolati e governance esplicita.

Il materiale originario conteneva una policy propria sui modelli. Non deve essere importata. Usare esclusivamente i profili definiti in:

`docs/agents/canonical-subagents.yaml`

Il materiale originario suggeriva confronti con il sistema legacy live. Sostituire “live” con:

- QA/staging/replica come default;
- produzione soltanto per operazioni read-only, idempotenti, autorizzate e senza side effect;
- dichiarazione dell'ambiente usato;
- redazione di PII e segreti;
- rate limit e dati di prova controllati.

---

## 4. Scope dei file

### File da modificare

1. `skills/mcp-master-orchestrator/SKILL.md`
2. `skills/mcp-master-orchestrator/evals/evals.json`
3. `skills/mcp-technical-analyst/SKILL.md`
4. `skills/mcp-technical-analyst/evals/evals.json`
5. `docs/mcp-skills-agents-development-guide.md`
6. `docs/skill-governance-matrix.md`
7. `scripts/build-routing-catalog.mjs`
8. `scripts/hooks/sophia-user-prompt-submit.mjs`
9. `scripts/smoke-codex-hooks.js`

### File da creare

1. `skills/mcp-master-orchestrator/references/legacy-modernization-workflow.md`
2. `skills/mcp-technical-analyst/references/legacy-system-inventory.md`
3. `skills/mcp-technical-analyst/references/legacy-source-recovery.md`
4. `scripts/hooks/routing-engine.mjs`
5. `scripts/test-routing-engine.mjs`
6. fixture sotto `fixtures/hooks/` per tutti i casi elencati nella sezione 14, inclusi:
   - inventory e reconstruction legacy;
   - source recovery offuscato;
   - confronto legacy/nuovo;
   - conflitto requisito/comportamento;
   - modernizzazione nominale vs operativa;
   - stessa frase affermativa e negata;
   - eval orchestrator completo;
   - anti-pattern analyst e orchestrator;
   - CFML cross-version;
   - regressioni rebase, SVG, multi-source e contesti repo.

I nomi delle fixture possono seguire la convenzione corrente, ma prompt, skill primaria, skill ammesse/escluse e diagnostica attesa devono restare invariati.

### File generati o verificati

- `scripts/hooks/routing-catalog.json`, prodotto esclusivamente da `scripts/build-routing-catalog.mjs`;
- `codex-hooks.generated.json` e `antigravity-hooks.generated.json`, se prodotti dai generatori, restano file locali ignorati;
- eventuali file agent derivati, soltanto tramite gli script canonici;
- nessun file generato deve essere modificato manualmente.

### File letti ma non modificati

- `scripts/install-user-runtime.js`, per verificare il percorso supportato di rigenerazione del catalogo;
- `.gitignore`, per confermare che `routing-catalog.json` è locale e ignorato;
- `scripts/generate-codex-hooks.js`;
- `scripts/generate-antigravity-hooks.js`.

### Fuori scope

Non modificare:

- server MCP;
- schema input dei tool;
- `package.json` o lockfile;
- `docs/agents/canonical-subagents.yaml`;
- profili agente, salvo drift generato automaticamente e gestito come indicato sotto;
- installer, salvo evidenza durante l'implementazione che il percorso di rigenerazione corrente non funzioni più.

### Compatibilità host

- Il routing `UserPromptSubmit` oggetto di questa specifica è operativo per Codex.
- Il generatore Antigravity corrente non installa un equivalente `UserPromptSubmit`.
- Non dichiarare parità di routing su Antigravity.
- Le skill Markdown restano comunque disponibili agli host che le indicizzano.

### Gestione del drift prodotto dagli script agenti

Prima del sync registrare:

```bash
git status --short
```

Poi eseguire:

```bash
node scripts/sync-portable-agents.js
node scripts/check-agents-doc.js
git status --short
```

Se `docs/agents/canonical-subagents.yaml` non è stato modificato ma il sync produce differenze:

1. considerarle drift preesistente;
2. non includerle automaticamente nella patch;
3. non ripristinare modifiche utente senza autorizzazione;
4. segnalarle separatamente;
5. fermarsi se non è possibile distinguere il drift dalla modifica corrente.

---

## 5. Modifica di `mcp-master-orchestrator/SKILL.md`

Applicare una modifica conservativa. Non riscrivere integralmente il file.

### 5.1 Frontmatter

Applicare una modifica **additiva** alla `description`. Non eliminare o indebolire trigger esistenti.

Devono restare espliciti almeno:

- bug triage;
- rebase/conflict-resolution coordination;
- reporting;
- onboarding;
- data migration;
- visual deliverables;
- post-fix validation;
- technical analysis da fonti miste.

Testo atteso, salvo trigger più recenti da preservare:

```yaml
---
name: mcp-master-orchestrator
description: Coordinate multi-step MCP work across docs, git, mantis, database, ColdFusion, browser, office, SVG/visual-asset, and technical-analysis flows. Use when the goal spans multiple phases such as bug triage, rebase/conflict-resolution coordination, reporting, onboarding, data migration, visual deliverables, post-fix validation, end-to-end legacy-system modernization or replatforming, or a technical analysis that starts from tickets, documents, attachments, commits, or mixed evidence.
---
```

La descrizione proposta è entro il budget locale consigliato di 400-600 caratteri. Se il file corrente contiene trigger ulteriori, preservarli e adattare il testo senza regressioni.

### 5.2 Matrice di decisione

Aggiungere una riga equivalente a:

```md
| Modernizzare o replatformizzare un sistema legacy end-to-end | `mcp-master-orchestrator`, con intake iniziale `mcp-technical-analyst` | skill sorgente/target, `mcp-code-reviewer`, `mcp-browser-automation`, `mcp-handoff-pack` |
```

### 5.3 Loop di coordinamento

Aggiungere una regola:

```md
Per una modernizzazione legacy end-to-end, delega discovery, inventory e parity contract a `mcp-technical-analyst`; avvia implementazione solo dopo il gate umano sui comportamenti da preservare/correggere e sui contratti condivisi.
```

### 5.4 Regole di escalation

Nella sezione esistente `## Regole di escalation prompt -> skill` aggiungere soltanto la regola positiva:

```md
- Usa questo orchestratore se il prompt richiede modernizzazione end-to-end con discovery, contratti, implementazione, confronto legacy/nuovo e cutover o handoff.
```

Non collocare gli anti-trigger nella sezione `Regole di escalation`: il catalog builder usa gli elementi puntati di tale sezione come keyword positive.

### 5.5 Anti-trigger

Creare una sezione autonoma e usare frasi direttamente matchabili:

```md
## Anti-trigger

- Non usare per solo inventory legacy.
- Non usare per source recovery isolato.
- Non usare per sola parity analysis.
- Non usare per singola modifica target.
```

Vincoli:

- ogni riga deve restare sotto 120 caratteri;
- preservare la formula `Non usare per`;
- `extractAntiPatterns()` deve leggere soltanto questa sezione;
- nessuna riga deve entrare nelle keyword o escalation positive;
- il runtime deve escludere l'orchestrator quando il pattern passa e non esiste un positive lock;
- non usare pattern descrittivi con articoli/copule inutili come `il task è una...`.

### 5.6 References

Aggiungere:

```md
* [references/legacy-modernization-workflow.md](references/legacy-modernization-workflow.md) per modernizzazioni o replatforming end-to-end con discovery, parity contract, implementazione, validazione e cutover.
```

---

## 6. Nuovo reference `legacy-modernization-workflow.md`

Creare il file con il contenuto seguente. Sono consentiti aggiustamenti minimi di stile, non cambi semantici.

````md
# 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.

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.

## 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.
````

---

## 7. Modifica di `mcp-technical-analyst/SKILL.md`

Applicare modifiche conservative.

### 7.1 Frontmatter

Applicare una modifica **additiva**. Preservare `dossiers` e l'anti-trigger esistente per tutti i task mono-dominio, non soltanto per quelli esecutivi.

Testo atteso, salvo trigger più recenti da preservare:

```yaml
---
name: mcp-technical-analyst
description: >
  Technical analysis skill for multi-source investigations across tickets,
  docs, commits, repos, DBs, attachments, and environments. Use for gap
  analysis, stato dell'arte, dossiers, requirement reconstruction, read-only
  legacy behavior inventory, source recovery, source-to-target parity
  analysis, or evidence-based Markdown deliverables. Do not use for
  single-domain tasks better handled by specialist skills.
---
```

Non rimuovere trigger o anti-trigger già presenti.

### 7.2 Quick Routing

Aggiungere una riga:

```md
| Legacy reconstruction | Ricostruire comportamento, inventory o parità source-to-target senza implementare | `ticket-first` o `document-first` + reference legacy |
```

### 7.3 Regole permanenti

Aggiungere:

```md
7. Per source recovery non eseguire payload legacy, non usare `eval` su contenuto non attendibile e registra provenienza/checksum degli artefatti derivati.
```

### 7.4 Stop conditions

Aggiungere alla sezione esistente:

```md
Quando la richiesta passa da inventory o parity analysis a implementazione, cutover o coordinamento multi-fase, completa l'analisi e consegna a `mcp-master-orchestrator` o alla skill specialistica.
```

### 7.5 Anti-trigger

Creare una sezione autonoma:

```md
## Anti-trigger

- Non usare per avvia implementazione operativa, esegui cutover applicativo o coordina flusso multi-fase.
```

Vincoli:

- mantenere la riga sotto 120 caratteri;
- preservare `Non usare per`;
- ogni alternativa deve contenere un verbo operativo e almeno due token significativi;
- non collocarla nella sezione `Regole di escalation`;
- non escludere citazioni nominali come `dossier sull'implementazione operativa`;
- il runtime deve trattarla come esclusione deterministica soltanto quando il verbo operativo è affermativo;
- una skill protetta da positive intent lock non viene esclusa.

### 7.6 References

Aggiungere:

```md
- [references/legacy-system-inventory.md](references/legacy-system-inventory.md): inventory comportamentale, parity matrix e handoff per modernizzazioni legacy.
- [references/legacy-source-recovery.md](references/legacy-source-recovery.md): recupero controllato di sorgenti offuscate o non leggibili senza esecuzione del payload.
```

---

## 8. Nuovo reference `legacy-system-inventory.md`

Creare il file con questo contenuto.

````md
# Legacy System Inventory

Usa questo riferimento quando serve ricostruire in modalità read-only il comportamento di un sistema legacy e produrre un contratto di parità per una futura modernizzazione.

Non implementare il target. Se la richiesta include implementazione, cutover o coordinamento multi-fase, completare l'inventory e passare a `mcp-master-orchestrator` o alla skill specialistica.

## Preflight

Richiedere o ricavare:

- `source_project_path` assoluto e read-only;
- repository e branch sorgente;
- commit/ref per baseline puntuali;
- `target_project_path` e repository/stack target, se già noti;
- `evidence_save_path` assoluto;
- eventuale `neutral_path`;
- ticket, requisito o documento funzionale;
- obiettivo dell'inventory;
- domini funzionali prioritari;
- ambienti e DB utilizzabili;
- mapping progetto → `.env` → DB → ambiente;
- vincoli su segreti, PII e dati cliente.

Non derivare il progetto dal `cwd` e non usare `.env` del repository MCP.

## Discovery

1. Leggere `AGENTS.md` ed eventuali `RULES.md`.
2. Identificare entry point, configurazione e dipendenze.
3. Cercare history, copie leggibili, backup e documentazione.
4. Aprire al massimo due filoni read-only paralleli, suddivisi per dominio.
5. Usare source recovery soltanto se non esiste una fonte leggibile.
6. Usare Playwright soltanto quando codice, dati, log e documenti non bastano.

## Suddivisione per domini

Preferire domini come:

- autenticazione e sessione;
- ricerca e navigazione;
- documenti e allegati;
- import/export;
- autorizzazioni;
- job e batch;
- integrazioni;
- configurazione;
- persistenza dati;
- errori e fallback.

Non suddividere soltanto per quantità di file.

## Template inventory

| Campo | Contenuto |
|---|---|
| ID | Identificativo stabile |
| Dominio | Area funzionale |
| Fonte | Repo, path, ref, simbolo o endpoint |
| Caller | Entry point o dipendenze |
| Input | Parametri e precondizioni |
| Logica osservata | Regole effettive |
| Accesso dati | Tabelle/query con valori sensibili redatti |
| Output | Shape, status, errori |
| Side effect | Scritture, notifiche, file, job |
| Edge case | Caso limite osservato |
| Stato legacy | Atteso, anomalo, non chiaro |
| Decisione | Preservare, correggere, chiarire |
| Proposta target | Equivalente previsto |
| Evidenza | Codice, test, log, query o documento |
| Confidenza | Alta, media, bassa |

## Regole sulle anomalie legacy

Non correggere silenziosamente.

Registrare:

```md
Legacy osservato:
Perché può essere un bug:
Dipendenze note:
Opzioni:
- preservare per compatibilità;
- correggere deliberatamente;
- introdurre feature flag;
- richiedere chiarimento.
Decisione:
Fonte della decisione:
```

Senza decisione verificabile usare `UNCLEAR`.

## Parity matrix

| Caso | Legacy | Target atteso | Esito | Evidenza | Decisione |
|---|---|---|---|---|---|
| ... | ... | ... | `MATCH` / `INTENTIONAL_CHANGE` / `LEGACY_BUG_PRESERVED` / `NEW_IMPLEMENTATION_BUG` / `UNCLEAR` | ... | ... |

## Sicurezza e redazione

Mantenere logica e struttura delle query, ma redigere:

- credenziali;
- token;
- segreti;
- host sensibili;
- PII;
- dati cliente;
- chiavi API;
- cookie o session ID.

Non copiare `.env` o valori reali nei deliverable.

## Output minimo

```md
# Legacy inventory — [sistema/modulo]

## Scope e baseline
## Fonti consultate
## Domini analizzati
## Evidenze osservate
## Inventory
## Anomalie legacy
## Parity matrix
## Inferenze tecniche
## Rischi
## Punti aperti
## Decisioni richieste
## Handoff consigliato
```

Separare sempre:

- evidenza osservata;
- inferenza;
- punto aperto;
- raccomandazione.

## Handoff

Passare a `mcp-master-orchestrator` quando sono richiesti:

- strategia;
- contratti;
- implementazione;
- validazione completa;
- cutover;
- rollback;
- handoff multi-skill.

Passare direttamente alla skill specialistica soltanto quando l'inventory ha ristretto il lavoro a una singola esecuzione di dominio.
````

---

## 9. Nuovo reference `legacy-source-recovery.md`

Creare il file con il contenuto seguente.

````md
# Legacy Source Recovery

Usa questo riferimento soltanto quando:

- non esiste una copia leggibile;
- history, backup e varianti non forniscono la sorgente;
- l'utente è autorizzato ad analizzare il codice;
- il recupero è necessario per inventory o parity analysis.

Non usare source recovery come prima scelta.

## Principi permanenti

1. Non eseguire il payload legacy.
2. Non usare `eval`, `exec`, include dinamici o import del codice recuperato.
3. Non contattare rete, DB o servizi esterni durante la decodifica.
4. Operare su una copia con checksum.
5. Conservare l'originale immutato.
6. Applicare limiti di dimensione, tempo e memoria.
7. Redigere segreti e PII.
8. Dichiarare che l'output derivato è evidenza da verificare, non sorgente autorevole automatica.

## Sequenza

### 1. Cercare una fonte leggibile

Controllare:

- history Git;
- branch/tag precedenti;
- file `_old`, `_orig`, backup o export;
- release package;
- artifact di build;
- documentazione;
- copie sibling;
- source map;
- versioni cliente/platform collegate.

Se esiste una copia affidabile, usare quella e fermare il recovery.

### 2. Congelare gli input

Registrare:

- path;
- dimensione;
- SHA-256;
- provenienza;
- ref/commit;
- autorizzazione;
- obiettivo.

Scrivere gli output in una directory separata e disposable.

### 3. Identificare lo strato

Classificare senza eseguire:

- encoding/compressione;
- string literal escaping;
- minificazione/ridenominazione;
- control-flow flattening;
- packing/encryption;
- bytecode o formato proprietario.

### 4. Decodificare senza esecuzione

Consentito:

- Base64 decode;
- decompressione tramite librerie dati;
- parsing AST;
- tokenizer/lexer;
- decoder di literal non eseguibile;
- source map;
- pretty printer.

Vietato:

- eseguire il file;
- eseguire la stringa decodificata;
- valutare token con `eval`;
- caricare il codice nel runtime applicativo;
- effettuare HTTP, query DB o scritture esterne.

### 5. Stringhe e literal

Preferire parser o AST già disponibili che restituiscano il valore del literal senza eseguire codice.

Se non esiste un decoder sicuro già disponibile, `mcp-technical-analyst` resta read-only e deve:

1. preservare il token originale;
2. documentare la grammatica minima e i requisiti del decoder;
3. indicare escape, Unicode, interpolazione e costrutti da rifiutare;
4. passare l'implementazione alla skill specialistica del linguaggio/runtime;
5. richiedere che l'utility operi soltanto in `neutral_path`, senza rete o credenziali;
6. riesaminare in modalità read-only output, checksum, test e limiti;
7. fermarsi su costrutti non riconosciuti.

L'analyst non crea codice, script o utility di decodifica.

Per stringhe interpolate:

- decodificare soltanto i segmenti literal;
- preservare variabili ed espressioni come token;
- non valutarle.

### 6. Isolamento

Quando serve un tool esterno:

- processo separato;
- working directory temporanea;
- rete disabilitata;
- filesystem limitato agli input/output;
- timeout;
- limite memoria;
- nessuna credenziale nell'ambiente;
- log dell'operazione.

### 7. Verifica

Confrontare:

- numero e posizione dei token;
- delimitatori;
- encoding;
- checksum dell'input;
- campioni di stringhe;
- tabelle/colonne con schema noto;
- costanti con caller osservati.

Non dichiarare il risultato semanticamente corretto soltanto perché è sintatticamente leggibile.

## Output

Produrre:

```md
## Source recovery

- Input:
- Provenienza:
- SHA-256:
- Tecnica:
- Tool/parser:
- Payload eseguito: no
- Rete utilizzata: no
- Output derivato:
- Verifiche:
- Limiti:
- Dati redatti:
- Confidenza:
```

## Stop conditions

Fermarsi se:

- l'autorizzazione è dubbia;
- serve eseguire il payload;
- il formato richiede chiavi non disponibili;
- il parser non distingue dati da codice;
- l'output può contenere segreti non redigibili;
- il recovery rischia side effect;
- la confidenza non è sufficiente per usarlo come evidenza.

In questi casi consegnare fatti, limiti e opzioni, senza improvvisare un decoder eseguibile.
````

---

## 10. Eval di `mcp-master-orchestrator`

Aggiornare `skills/mcp-master-orchestrator/evals/evals.json`.

Preservare gli eval esistenti. Aggiungere oggetti equivalenti ai seguenti usando ID successivi liberi.

```json
{
  "id": 6,
  "prompt": "Modernizza un'applicazione PHP legacy verso Sophia/Yii: ricostruisci comportamento, definisci contratti, implementa per slice, confronta legacy e nuovo e prepara cutover e handoff.",
  "expected_output": "Routing end-to-end verso mcp-master-orchestrator, con mcp-technical-analyst per intake/inventory e skill specialistiche per implementazione, review e validazione.",
  "expectations": [
    "Riconosce il task come multi-fase e non come semplice migrazione mono-dominio",
    "Delega inventory e parity contract a mcp-technical-analyst",
    "Usa massimo un implementer per project_path",
    "Prevede review spec-compliance, validazione comparativa, cutover e rollback",
    "Non richiede una skill legacy-migration separata",
    "La priorità modernization prevale sull'intent legacy-analysis-only concorrente"
  ]
}
```

```json
{
  "id": 7,
  "prompt": "Inventaria endpoint, query, output ed edge case di questo backend PHP legacy. Non implementare ancora nulla.",
  "expected_output": "Routing diretto verso mcp-technical-analyst; il workflow end-to-end dell'orchestrator non viene attivato.",
  "expectations": [
    "Classifica la richiesta come analisi read-only",
    "Instrada a mcp-technical-analyst",
    "Non avvia implementer, cutover o workflow di delivery"
  ]
}
```

```json
{
  "id": 8,
  "prompt": "Porta una feature CFML da una versione del prodotto a un'altra usando una directory neutrale con conventions.md e touched-files.md.",
  "expected_output": "Routing verso mcp-coldfusion-developer in Cross-Version Migration Mode.",
  "expectations": [
    "Riconosce il caso già coperto dalla skill CFML",
    "Non attiva il workflow generico legacy modernization",
    "Preserva ruoli Provider/Consumer e validatore esistenti"
  ]
}
```

```json
{
  "id": 9,
  "prompt": "Avvia quattro implementer in parallelo su moduli diversi dello stesso checkout per accelerare la modernizzazione.",
  "expected_output": "Rifiuto del parallelismo di scrittura nello stesso project_path e proposta di sequenza con un solo implementer attivo.",
  "expectations": [
    "Applica il limite massimo di un implementer per project_path",
    "Consente al massimo due scout read-only in parallelo",
    "Non usa la disgiunzione apparente dei file per aggirare la governance"
  ]
}
```


```json
{
  "id": 10,
  "prompt": "Voglio modernizzare il legacy e preparare cutover e rollback.",
  "expected_output": "Routing verso mcp-master-orchestrator per una modernizzazione operativa multi-fase.",
  "expectations": [
    "Riconosce modernizzare come azione affermativa",
    "Richiede almeno un segnale multi-fase",
    "Non confonde il task con una sola analisi read-only"
  ]
}
```

```json
{
  "id": 11,
  "prompt": "Non limitarti ad analizzare: modernizza il target e prepara l'handoff.",
  "expected_output": "Routing verso mcp-master-orchestrator; la negazione appartiene alla clausola analitica e non al verbo modernizza.",
  "expectations": [
    "Applica la negazione localmente alla clausola",
    "Attiva modernization end-to-end",
    "Non lascia prevalere analysis-only"
  ]
}
```

Aggiornare `eval_focus` aggiungendo:

```json
"legacy-modernization-routing",
"legacy-inventory-anti-trigger",
"cfml-cross-version-anti-overlap",
"single-implementer-per-project-path",
"nominal-vs-operational-modernization",
"local-negation-scope"
```

---

Tutti gli eval orchestrator `6–11` devono avere una fixture runtime corrispondente.

---

## 11. Eval di `mcp-technical-analyst`

Aggiornare `skills/mcp-technical-analyst/evals/evals.json`.

Preservare gli eval esistenti. Aggiungere:

```json
{
  "id": 7,
  "prompt": "Ricostruisci il comportamento di un sistema legacy da codice, documentazione e DB. Produci inventory e parity matrix senza implementare il target.",
  "expected_output": "Analisi read-only multi-sorgente con inventory strutturato, separazione fatti/inferenze e handoff verso orchestrator.",
  "files": [],
  "expectations": [
    "Usa mcp-technical-analyst come owner",
    "Organizza l'inventory per dominio funzionale",
    "Separa evidenza, inferenza, punto aperto e decisione",
    "Non applica modifiche al target"
  ]
}
```

```json
{
  "id": 8,
  "prompt": "L'unica sorgente PHP disponibile è offuscata. Recupera SQL e costanti utili all'inventory.",
  "expected_output": "Source recovery controllato senza eseguire payload e senza usare eval.",
  "files": [],
  "expectations": [
    "Cerca prima copie leggibili e history",
    "Registra provenienza e checksum",
    "Vieta eval o esecuzione del payload",
    "Usa parser, AST o decoder di literal non eseguibile",
    "Dichiara limiti e confidenza"
  ]
}
```

```json
{
  "id": 9,
  "prompt": "Confronta il nuovo endpoint con il legacy. Codice, test e log sono già sufficienti a stabilire la parità.",
  "expected_output": "Confronto basato sulle evidenze disponibili senza attivare automaticamente Playwright.",
  "files": [],
  "expectations": [
    "Evita browser automation quando non necessaria",
    "Classifica le discrepanze",
    "Documenta la conclusività delle evidenze"
  ]
}
```

```json
{
  "id": 10,
  "prompt": "Il legacy restituisce un valore incoerente con il requisito funzionale. Decidi cosa implementare nel nuovo sistema.",
  "expected_output": "Conflitto esplicito, nessuna decisione inventata e richiesta di gate umano.",
  "files": [],
  "expectations": [
    "Distingue requisito e comportamento osservato",
    "Marca il punto come UNCLEAR finché non esiste una decisione",
    "Non corregge né replica silenziosamente il bug"
  ]
}
```

```json
{
  "id": 11,
  "prompt": "Produci un dossier sui rischi dell'implementazione operativa del legacy, senza eseguire modifiche.",
  "expected_output": "Routing e comportamento analyst read-only: la citazione nominale dell'implementazione non attiva l'anti-pattern operativo.",
  "files": [],
  "expectations": [
    "Mantiene mcp-technical-analyst come owner",
    "Non interpreta la citazione nominale come richiesta esecutiva",
    "Non applica modifiche al target",
    "Separa evidenze, rischi e punti aperti"
  ]
}
```


```json
{
  "id": 12,
  "prompt": "Produci un dossier sui rischi della modernizzazione legacy e del cutover, senza implementare.",
  "expected_output": "Routing analyst read-only: i sostantivi modernizzazione e cutover non sono sufficienti per un intent operativo.",
  "files": [],
  "expectations": [
    "Mantiene mcp-technical-analyst come owner",
    "Non assegna un positive lock all'orchestrator",
    "Non applica modifiche al target"
  ]
}
```

```json
{
  "id": 13,
  "prompt": "Non modernizzare: inventaria soltanto il legacy.",
  "expected_output": "Routing verso mcp-technical-analyst; il verbo modernizzare è negato nella stessa clausola.",
  "files": [],
  "expectations": [
    "Gestisce la negazione locale",
    "Attiva legacy-analysis-only",
    "Esclude mcp-master-orchestrator"
  ]
}
```

Aggiornare `eval_focus` aggiungendo:

```json
"legacy-behavior-inventory",
"safe-source-recovery",
"legacy-target-parity",
"legacy-conflict-human-gate",
"analytical-mention-vs-operational-intent",
"nominal-modernization-analysis",
"negated-modernization-analysis"
```

---

Vincolo: gli eval analyst `7–13` devono essere coperti da fixture eseguibili; la sola validazione JSON non costituisce prova di routing.

---

## 12. Documentazione repository

### 12.1 `docs/mcp-skills-agents-development-guide.md`

Aggiungere una sezione compatta vicino ai workflow/routing:

```md
### Legacy modernization end-to-end

Per modernizzazioni o replatforming che includono discovery, contratti, implementazione, confronto legacy/nuovo e cutover:

1. usare `mcp-master-orchestrator` come coordinatore;
2. delegare inventory e parity analysis a `mcp-technical-analyst`;
3. usare una sola skill/implementer target per `project_path`;
4. validare con `mcp-code-reviewer` e tool pertinenti;
5. usare browser automation soltanto quando UI/runtime sono necessari;
6. preparare cutover, osservabilità e rollback.

Anti-overlap:

- solo inventory/source recovery/parity → `mcp-technical-analyst`;
- migrazione CFML cross-version con directory neutrale → `mcp-coldfusion-developer`;
- singola modifica target → skill specialistica.
```

Correggere inoltre l'indicazione sul catalogo routing:

- `scripts/build-routing-catalog.mjs` genera `scripts/hooks/routing-catalog.json`;
- `scripts/generate-codex-hooks.js` genera la configurazione hook Codex;
- i due generatori non sono intercambiabili.

Aggiungere una nota host:

- `UserPromptSubmit` e il routing qui descritto sono verificati su Codex;
- il generatore Antigravity corrente non espone un equivalente;
- non dichiarare parità cross-host.

Non modificare la fonte canonica dei modelli agente.

### 12.2 `docs/skill-governance-matrix.md`

Aggiornare le righe esistenti:

- `mcp-technical-analyst`: copertura legacy inventory/source recovery/parity e relativi eval runtime;
- `mcp-master-orchestrator`: routing legacy modernization end-to-end e anti-overlap;
- eval coverage: includere casi nominali vs operativi, negazioni, conflitti e anti-pattern;
- script support: indicare il motore routing/test repository-level, senza attribuirlo a una cartella `scripts/` locale della skill.

Non aggiungere una riga per una nuova skill.

### 12.3 Checklist PR

La consegna finale deve riportare una checklist coerente con `docs/pr-checklist-mcp.md`, almeno per:

- scope;
- compatibilità legacy;
- smoke/test;
- documentazione;
- schema MCP;
- setup/rigenerazione catalogo;
- restart;
- rischio cross-host;
- drift agenti.

---

## 13. Routing catalog e motore runtime

La modifica non può limitarsi ai frontmatter. Il runtime deve essere reso verificabile senza trasformare il hook in un classificatore complesso o introdurre dipendenze esterne.

### 13.1 Catalog builder e schema v2

Modificare `scripts/build-routing-catalog.mjs` in modo incrementale.

#### Versione catalogo

Il catalogo generato deve dichiarare:

```js
version: 2
```

Il cambio è obbligatorio perché vengono introdotti campi semantici nuovi:

- `priority`;
- `affirmativeAny`;
- `unlessAny`;
- `suppress`;
- diagnostica di intent/lock/esclusioni nel motore.

Gli intent preesistenti senza `priority` sono interpretati come `0`.

#### Anti-pattern

Riscrivere `extractAntiPatterns()` affinché analizzi soltanto il contenuto della sezione esatta:

```md
## Anti-trigger
```

La sezione termina al successivo heading `##`, a `---` o a fine file.

Vincoli:

- non scansionare frontmatter, quick routing, stop conditions o paragrafi generici;
- non trasformare anti-trigger preesistenti fuori dalla sezione dedicata in regole runtime;
- non includere gli anti-trigger in `extractEscalationPhrases()`;
- non troncare pattern validi;
- mantenere il campo `antiPatterns`;
- produrre per ogni skill un elenco deterministico.

Dopo la generazione verificare esplicitamente:

- orchestrator: soltanto i quattro anti-trigger definiti nella sezione 5.5;
- analyst: soltanto il pattern operativo definito nella sezione 7.5;
- code reviewer e skill non migrate: nessun nuovo anti-pattern operativo accidentale;
- nessun anti-trigger tra le escalation positive.

#### Intent strutturali

Aggiungere tre intent.

```js
{
  id: 'legacy-analysis-only',
  description: 'Legacy/source investigation without target implementation',
  priority: 100,
  signals: [
    {
      any: [
        'legacy',
        'sistema esistente',
        'codice esistente',
        'sorgente offuscata',
        'codice offuscato',
        'offuscata',
        'offuscato'
      ],
      label: 'legacy-or-source'
    },
    {
      any: [
        'inventaria', 'inventario', 'inventory',
        'ricostruisci', 'ricostruzione',
        'source recovery', 'recupero sorgente', 'recupera',
        'deoffusca', 'deobfuscate',
        'confronta', 'confronto', 'equivalenza',
        'parity', 'parità',
        'analizza', 'analisi tecnica',
        'dossier', "stato dell'arte",
        'requisito funzionale',
        'incoerente con il requisito'
      ],
      label: 'analysis'
    }
  ],
  minDistinctGroups: 2,
  unlessAny: [
    'modernizza', 'modernizzare',
    'replatformizza', 'replatformizzare',
    'riscrivi', 'riscrivere',
    'implementa il target', 'implementare il target',
    'implementa la migrazione', 'implementare la migrazione',
    'implementa per slice', 'implementare per slice',
    'procedi con implementazione', 'procedere con implementazione',
    'avvia implementazione', 'avviare implementazione',
    'esegui il cutover', 'eseguire il cutover',
    'prepara il cutover', 'preparare il cutover',
    'prepara cutover', 'preparare cutover',
    'prepara il rollback', 'preparare il rollback',
    'coordina il cutover', 'coordinare il cutover'
  ],
  boost: { skillId: 'mcp-technical-analyst', score: 6 },
  suppress: ['mcp-master-orchestrator']
}
```

Regole:

- `offuscata + recupera/inventory` deve coprire il source-recovery eval;
- `legacy + confronta/equivalenza` deve coprire parity;
- `legacy + requisito funzionale/incoerente` deve coprire il conflitto;
- `unlessAny` considera soltanto frasi operative affermative;
- i sostantivi `modernizzazione`, `modernization`, `replatforming` e `rewrite` non bloccano analysis-only da soli.

```js
{
  id: 'legacy-modernization-end-to-end',
  description: 'Affirmative end-to-end legacy modernization or replatforming',
  priority: 200,
  signals: [
    {
      affirmativeAny: [
        'modernizza', 'modernizzare',
        'replatformizza', 'replatformizzare',
        'riscrivi', 'riscrivere',
        'avvia la modernizzazione',
        'implementa il target', 'implementare il target',
        'implementa la migrazione', 'implementare la migrazione',
        'implementa per slice', 'implementare per slice',
        'procedi con implementazione', 'procedere con implementazione'
      ],
      label: 'action'
    },
    {
      any: [
        'end-to-end', 'cutover', 'rollback', 'handoff',
        'confronto legacy/nuovo', 'source-to-target',
        'ricostruisci', 'ricostruzione',
        'inventory', 'parity', 'contratti condivisi'
      ],
      label: 'multiphase'
    }
  ],
  minDistinctGroups: 2,
  boost: { skillId: 'mcp-master-orchestrator', score: 8 }
}
```

Vincoli:

- serve sempre un verbo operativo affermativo;
- `modernizzazione`, `modernization`, `replatforming` e `rewrite` sono contesto, non azione;
- `Produci un dossier sui rischi della modernizzazione e del cutover` non deve attivare l'intent;
- `Voglio modernizzare il legacy e preparare cutover` deve attivarlo.

```js
{
  id: 'cfml-cross-version',
  description: 'CFML migration between product versions through neutral workspace',
  priority: 300,
  signals: [
    {
      any: ['cfml', 'coldfusion'],
      label: 'cfml'
    },
    {
      any: [
        'cross-version', 'tra versioni', 'directory neutrale',
        'conventions.md', 'touched-files.md'
      ],
      label: 'migration'
    }
  ],
  minDistinctGroups: 2,
  boost: { skillId: 'mcp-coldfusion-developer', score: 8 },
  suppress: ['mcp-master-orchestrator']
}
```

Priorità:

```text
cfml-cross-version (300)
> legacy-modernization-end-to-end (200)
> legacy-analysis-only (100)
> intent preesistenti/default (0)
```

### 13.2 Motore puro e hook sottile

Creare `scripts/hooks/routing-engine.mjs`.

Il modulo deve contenere funzioni pure e testabili per:

- normalizzazione;
- tokenizzazione/clausole;
- match di frasi affermative;
- match `unlessAny`;
- match degli intent;
- anti-pattern;
- scoring finale;
- lock, suppression ed esclusioni.

API consigliata:

```js
export function evaluateRouting({ text, tokens, repoContext, catalog, baseScores }) {
  return {
    scores,
    matchedIntents,
    positiveLocks,
    suppressions,
    antiPatternMatches,
    excludedSkills,
    rankedSkills,
    catalogStatus
  };
}
```

`rankedSkills` deve contenere almeno:

```js
[{ skillId, score, rank }]
```

`matchedIntents` deve contenere:

```js
[{ intentId, priority, boostedSkillId, suppress }]
```

Modificare `scripts/hooks/sophia-user-prompt-submit.mjs` affinché:

1. carichi catalogo e contesto;
2. deleghi la parte deterministica al motore puro;
3. mantenga massimo due hint testuali;
4. non esponga diagnostica nell'output utente normale;
5. mantenga il comportamento conservativo e non bloccante.

### 13.3 Catalog loader e compatibilità

Il loader deve aspettarsi `catalog.version === 2`.

Stati minimi:

```text
ok
missing
invalid-json
invalid-schema
unsupported-version
```

Comportamento:

- `ok`: routing completo;
- `invalid-schema`: distinto da `invalid-json`, disabilita il routing catalog-dependent, mantiene il hook non bloccante e viene registrato soltanto nella diagnostica e negli analytics, non in `additionalContext`;
- altro stato: nessun hint skill catalog-dependent;
- hint indipendenti/guardrail possono restare se non dipendono dal catalogo;
- nessun crash o stack trace;
- registrare best-effort un evento diagnostico locale;
- rendere lo stato visibile al motore/test, non nel normale `additionalContext`.

Il catalogo è ignorato da Git e viene rigenerato dall'installer. Percorso supportato:

```bash
node scripts/build-routing-catalog.mjs
node scripts/install-user-runtime.js --only-changed
```

Il secondo comando rigenera anche il catalogo prima di compilare il piano. Non serve riavviare server MCP.

### 13.4 Matcher boundary-aware e negation-aware

Usare lo stesso matcher per `affirmativeAny` e `unlessAny`.

Definizione minima:

- normalizzare case, accenti, punteggiatura e spazi;
- matchare parole intere e sequenze complete;
- suddividere il testo in clausole tramite `.`, `;`, `:`, newline e connettivi forti;
- una negazione (`non`, `senza`, `evita di`) vale soltanto nella stessa clausola;
- la negazione deve precedere il verbo entro una finestra massima documentata, consigliata `3` token;
- una nuova clausola interrompe lo scope della negazione;
- niente fuzzy matching.

Casi obbligatori:

| Prompt | `modernizza/implementare` |
|---|---:|
| `implementare il target` | affermativo |
| `senza implementare il target` | negato |
| `non implementare il target` | negato |
| `non modernizzare` | negato |
| `modernizza end-to-end` | affermativo |
| `non limitarti ad analizzare: modernizza il target` | affermativo nella seconda clausola |

### 13.5 Intent, lock e suppression

Per ogni intent:

```js
const priority = Number.isFinite(intent.priority) ? intent.priority : 0;
```

Ordinamento:

1. priorità decrescente;
2. posizione originale nel catalogo a parità.

Mantenere:

```js
positiveLocks: Map<skillId, highestPriority>
suppressions: Array<{ skillId, priority, sourceIntentId }>
```

Gli intent con priorità `0` possono assegnare boost, ma non costituiscono un lock protettivo contro gli anti-pattern. Un lock protegge soltanto se `highestPriority > 0`.

Applicazione:

1. scoring base;
2. match di tutti gli intent;
3. ordinamento stabile;
4. boost e lock;
5. raccolta suppression;
6. esclusioni anti-pattern sulle skill non protette;
7. suppression;
8. ranking finale.

Regola di suppression:

```js
const targetLockPriority = positiveLocks.get(skillId) || 0;
const canSuppress = suppressorPriority > targetLockPriority;
```

La superiorità deve essere stretta:

- priorità `100` sopprime una skill senza lock (`0`);
- priorità `100` non sopprime un lock `100`;
- `300` sopprime il lock orchestrator `200`;
- `100` non sopprime il lock orchestrator `200`.

### 13.6 Anti-pattern come esclusione deterministica

Implementare:

```js
function matchesAntiPattern(pattern, promptText) {
  // divide alternative solo su virgola, " o " e " oppure "
  // conserva i verbi operativi
  // matcha frase completa oppure tutti i token significativi
  // nella stessa clausola e in una finestra massima di 8 token
}
```

Regole:

- almeno due token significativi;
- nessun match su un singolo token generico;
- non spezzare parole che contengono `o`;
- stopword soltanto di servizio/routing;
- preservare `avvia`, `esegui`, `coordina`, `implementa`, `modifica`;
- verbo operativo negato → nessun match;
- citazione nominale → nessun match.

Quando un pattern passa:

```js
const lockPriority = positiveLocks.get(skillId) || 0;
if (lockPriority <= 0) {
  excludedSkills.add(skillId);
}
```

Non usare una penalità fissa `-6`: una skill esclusa non deve riapparire sopra soglia per accumulo di keyword.

### 13.7 Catalogo generato

Eseguire:

```bash
node scripts/build-routing-catalog.mjs
```

Verificare:

- `version === 2`;
- tre intent presenti;
- priorità `300/200/100`;
- intent preesistenti interpretati con priorità `0`;
- anti-pattern soltanto da sezioni dedicate;
- anti-trigger assenti dalle escalation positive;
- nessuna skill `legacy-migration`;
- nessun sidecar inesistente;
- trigger e categorie preesistenti preservati.

Il controllo deve produrre evidenza strutturata, non soltanto exit code `0`.

---

## 14. Validazioni obbligatorie

### Stato iniziale

Prima di eseguire generatori o sync:

```bash
git status --short
```

Registrare modifiche preesistenti e non inglobarle automaticamente.

### Comandi

Eseguire dalla root:

```bash
node --check scripts/build-routing-catalog.mjs
node --check scripts/hooks/routing-engine.mjs
node --check scripts/hooks/sophia-user-prompt-submit.mjs
node scripts/build-routing-catalog.mjs
node scripts/check-skill-evals-json.js
node scripts/test-routing-engine.mjs
node scripts/smoke-codex-hooks.js
git status --short
node scripts/sync-portable-agents.js
node scripts/check-agents-doc.js
git status --short
git diff --check
```

Ruolo dei controlli:

- `check-skill-evals-json.js`: sintassi JSON;
- `test-routing-engine.mjs`: semantica pura, diagnostica e compatibilità catalogo;
- `smoke-codex-hooks.js`: comportamento end-to-end del hook e testo degli hint.

### Rigenerazione runtime

Poiché `routing-catalog.json` è ignorato da Git:

- sviluppo/CI locale: `node scripts/build-routing-catalog.mjs`;
- aggiornamento utente supportato: `node scripts/install-user-runtime.js --only-changed`;
- restart server MCP: **no**;
- refresh catalogo routing: **sì**;
- modifica package/lockfile: **no**;
- migration storage: **no**;
- modifica schema MCP: **no**.

Eseguire almeno un test da catalogo assente o obsoleto in una directory temporanea, senza cancellare file utente.

### Test puri del routing engine

`node scripts/test-routing-engine.mjs` deve coprire:

1. normalizzazione e boundary;
2. negazione locale;
3. verbo imperativo e infinitivo;
4. sostantivo nominale vs azione;
5. priorità `300/200/100/0`;
6. ordine stabile a parità;
7. priorità mancante/non numerica → `0`;
8. suppression strettamente superiore;
9. positive lock;
10. anti-pattern come esclusione;
11. intent legacy con priorità `0` non protettivo contro anti-pattern;
12. citazione nominale non esclusa;
13. catalogo v2 valido;
14. catalogo v1, mancante e JSON invalido;
15. diagnostica completa.

### Fixture runtime obbligatorie

Eseguire i casi intent-only con `cwd`/payload puntato a `neutralRoot`, per evitare boost repo accidentali.

| Prompt | Skill primaria | Skill ammesse | Skill escluse |
|---|---|---|---|
| `Inventaria questo PHP legacy` | analyst | analyst | orchestrator |
| `Ricostruisci il legacy senza implementare il target` | analyst | analyst | orchestrator |
| `L'unica sorgente PHP disponibile è offuscata. Recupera SQL e costanti utili all'inventory.` | analyst | analyst, DB | orchestrator |
| `Confronta il nuovo endpoint con il legacy...` | analyst | analyst | browser |
| `Il legacy restituisce un valore incoerente con il requisito funzionale...` | analyst | analyst | orchestrator |
| `Produci un dossier sui rischi dell'implementazione operativa del legacy` | analyst | analyst | — |
| `Produci un dossier sui rischi della modernizzazione legacy e del cutover, senza implementare.` | analyst | analyst | orchestrator |
| `Non modernizzare: inventaria soltanto il legacy` | analyst | analyst | orchestrator |
| `Voglio modernizzare il legacy e preparare cutover e rollback` | orchestrator | orchestrator | — |
| `Non limitarti ad analizzare: modernizza il target e prepara l'handoff` | orchestrator | orchestrator | analyst come primaria |
| prompt completo eval orchestrator `id: 6` | orchestrator | orchestrator, Yii | — |
| `Analisi tecnica e dossier completati: avvia implementazione operativa del target Yii` | Yii | Yii | analyst |
| `Porta feature CFML tra versioni con directory neutrale` | CFML | CFML | orchestrator |
| `Modernizza end-to-end una feature CFML tra versioni con directory neutrale` | CFML | CFML | orchestrator |
| `Prepara un piano per una singola modifica target Yii` | Yii | Yii | orchestrator |

Per gli eval analyst `7–13` e orchestrator `6–11` deve esistere una fixture o un caso test equivalente.

### Assertion

Non limitarsi a sottostringhe casuali.

Test puri:

- `rankedSkills[0].skillId` uguale alla skill primaria;
- insieme delle skill osservate contenuto nell'insieme ammesso;
- skill escluse assenti da `rankedSkills`;
- `matchedIntents`, priorità, lock, suppression ed esclusioni uguali all'atteso.

Smoke hook:

- `assertIncludes` sulla skill primaria;
- `assertNotIncludes` sulle skill concretamente escluse;
- massimo due hint;
- nessun output per catalogo incompatibile quando non esistono hint indipendenti.

### Regressioni preesistenti

Preservare e ampliare:

1. multi-source analysis;
2. ticket-driven;
3. write-then-validate;
4. rebase/conflict resolution;
5. SVG/visual deliverable;
6. SQL;
7. Office;
8. browser;
9. contesto neutro;
10. contesto CFML;
11. contesto Yii;
12. docs + memory;
13. guardrail subagent;
14. nessuna escalation analyst sui task mono-dominio.

### Evidenza di esecuzione

Compilare dalla diagnostica:

| Prompt | Intent/priorità | Lock | Suppression | Anti-pattern/esclusioni | Primaria | Esito |
|---|---|---|---|---|---|---:|
| ... | ... | ... | ... | ... | ... | PASS/FAIL |

Non dichiarare il routing validato senza:

- test puri verdi;
- smoke hook verdi;
- catalogo v2 ispezionato;
- prova della priorità applicata;
- prova dell'esclusione anti-pattern;
- prova del comportamento su catalogo v1/mancante.

### Verifica frontmatter, alias e Markdown

Confermare:

- trigger preesistenti preservati;
- alias logici mappati a `project_path`/`save_path`;
- nessun nuovo campo schema MCP;
- source recovery non produce codice tramite analyst;
- link e heading validi;
- nessun riferimento allo ZIP come prerequisito;
- nessun `eval`;
- nessun modello o path cliente hardcoded;
- nessun file agent derivato incluso per drift.

---

## 15. Criteri di accettazione

L'implementazione è completa solo se tutti i punti risultano veri.

### Routing

- [ ] End-to-end modernization con verbo operativo + segnale multi-fase → orchestrator.
- [ ] Inventory/source recovery/parity/conflitto requisito soltanto → analyst.
- [ ] I sostantivi `modernizzazione`, `modernization`, `replatforming`, `rewrite` non creano un lock operativo.
- [ ] `modernizzare`, `replatformizzare`, `riscrivere` e forme imperative affermative sono riconosciute.
- [ ] Negazione locale gestita su `non`, `senza`, `evita di`.
- [ ] Una nuova clausola interrompe lo scope della negazione.
- [ ] CFML cross-version prevale sul modernization generico.
- [ ] Singola modifica target → skill specialistica.
- [ ] Review diff/branch/PR → reviewer.
- [ ] Browser soltanto quando necessario.
- [ ] Catalogo `version: 2`.
- [ ] Priorità `300/200/100`, default `0`.
- [ ] Ordine stabile a parità.
- [ ] Suppression soltanto se priorità strettamente superiore al lock.
- [ ] Soltanto positive lock con priorità maggiore di `0` proteggono dagli anti-pattern.
- [ ] Anti-pattern estratti soltanto da `## Anti-trigger`.
- [ ] Anti-pattern applicati come esclusione deterministica, non penalità.
- [ ] Citazioni nominali non attivano anti-pattern operativi.
- [ ] Tutti gli eval analyst `7–13` e orchestrator `6–11` hanno prova runtime.

### Motore e diagnostica

- [ ] `routing-engine.mjs` è puro e testabile.
- [ ] Il hook mantiene massimo due hint.
- [ ] Diagnostica espone intent, priorità, lock, suppression, anti-pattern, esclusioni e ranking.
- [ ] Catalogo mancante/invalido/v1 non causa crash né routing obsoleto.
- [ ] Catalogo v2 valido produce routing completo.
- [ ] Nessuna eccezione hardcoded sull'intero prompt.

### Governance

- [ ] Alias logici mappati a `project_path` e `save_path`.
- [ ] Nessun nuovo campo schema MCP.
- [ ] Source e target non derivati dal `cwd`.
- [ ] Source read-only; target unico checkout write-capable.
- [ ] Nessuna nuova skill o agente.
- [ ] Nessuna policy modelli duplicata.
- [ ] Un solo implementer per `project_path`.
- [ ] Massimo due scout read-only.
- [ ] Cross-host dichiarato: Codex sì, parità Antigravity no.

### Sicurezza

- [ ] Source recovery senza esecuzione payload.
- [ ] Nessun uso di `eval`.
- [ ] Checksum e provenienza registrati.
- [ ] Analyst non implementa decoder/script.
- [ ] Decoder specialistico confinato in `neutral_path`.
- [ ] Produzione soltanto read-only e autorizzata.
- [ ] Segreti e PII redatti.

### Completezza workflow

- [ ] Inventory e parity matrix.
- [ ] Gate umano sui bug legacy.
- [ ] Contratti condivisi.
- [ ] Implementazione incrementale.
- [ ] Integrazione single-owner.
- [ ] Spec compliance.
- [ ] Riconciliazione dati quando applicabile.
- [ ] Cutover, osservabilità e rollback.
- [ ] Handoff.

### Repository quality e distribuzione

- [ ] Eval JSON validi.
- [ ] Test puri verdi.
- [ ] Smoke hook verdi.
- [ ] Regressioni preesistenti verdi.
- [ ] Catalogo rigenerato e non editato manualmente.
- [ ] Catalogo runtime aggiornabile tramite installer.
- [ ] Refresh catalogo documentato.
- [ ] Restart MCP: no.
- [ ] Package/lockfile invariati.
- [ ] Schema MCP invariati.
- [ ] Drift agenti fuori scope.
- [ ] Discrepanza `master`/`rework` riportata.
- [ ] Guida corretta sul generatore catalogo.
- [ ] Checklist PR compilata.
- [ ] `git diff --check` passa.

---

## 16. Sequenza di implementazione consigliata per Codex

1. Verificare branch `master`, governance, `RULES.md` e `git status --short`.
2. Confermare che la nota `rework` non cambi il branch.
3. Creare i tre reference di workflow.
4. Aggiornare analyst/orchestrator ed eval preservando trigger esistenti.
5. Creare sezioni `## Anti-trigger` dedicate e direttamente matchabili.
6. Modificare il builder:
   - catalogo v2;
   - anti-pattern soltanto da sezione dedicata;
   - intent `300/200/100`;
   - default priority `0`.
7. Estrarre `scripts/hooks/routing-engine.mjs`.
8. Implementare matcher boundary-aware, clause-aware e negation-aware.
9. Implementare lock, suppression strettamente superiore ed esclusioni anti-pattern.
10. Adattare il hook senza cambiare il limite di due hint.
11. Creare `scripts/test-routing-engine.mjs`.
12. Aggiungere fixture per tutti gli eval e regressioni.
13. Aggiornare guida, governance matrix e nota cross-host.
14. Rigenerare e ispezionare catalogo v2.
15. Eseguire test puri, smoke hook, eval JSON e regressioni.
16. Verificare catalogo mancante/v1/v2.
17. Eseguire sync/check agenti e separare drift.
18. Eseguire `git diff --check`.
19. Riesaminare scope, schema MCP, package/lockfile e file generati.
20. Consegnare:
    - file modificati/creati;
    - decisioni;
    - comandi;
    - diagnostica routing;
    - tabella smoke;
    - catalog status/version;
    - drift;
    - checklist PR;
    - rischio cross-host;
    - nota `refresh catalogo: sì`;
    - nota `restart MCP: no`;
    - nota `schema MCP modificati: no`.

Non creare commit o PR salvo richiesta separata.

---

## 17. Prompt pronto per Codex

```text
Implementa la specifica canonica
specifica-implementativa-legacy-modernization.md
nel repository corrente.

Il documento è FINAL e self-contained. Non chiedere né cercare lo ZIP.
Il branch target è master; la nota rework è soltanto una discrepanza documentale.

Leggi AGENTS.md, documenti richiamati, eventuali RULES.md e file target.
Registra git status --short prima di modificare o generare file.
Applica una patch incrementale e preserva tutti i trigger esistenti.

Crea i tre reference legacy.
Separa gli anti-trigger in sezioni esatte ## Anti-trigger.
Il catalog builder deve leggere anti-pattern soltanto da tali sezioni.
Porta routing-catalog.json a version 2.

Aggiungi gli intent:
- cfml-cross-version priority 300;
- legacy-modernization-end-to-end priority 200;
- legacy-analysis-only priority 100;
- intent preesistenti/default priority 0.

Modernization richiede sempre un verbo operativo affermativo e un segnale multi-fase.
I sostantivi modernizzazione/modernization/replatforming/rewrite non bastano.
Copri source recovery, confronto legacy/nuovo e conflitto requisito nel routing analyst.

Estrai un motore puro scripts/hooks/routing-engine.mjs.
Implementa matching boundary-aware, clause-aware e negation-aware.
La negazione vale soltanto nella stessa clausola.
Mantieni lock, suppression ed esclusioni diagnosticabili.
Una suppression passa soltanto con priorità strettamente superiore al lock.
Gli intent preesistenti con priorità 0 possono dare boost ma non proteggono dagli anti-pattern.
Gli anti-pattern escludono deterministicamente skill non protette; niente penalità -6.

Il hook user-facing mantiene massimo due hint.
Su catalogo mancante, invalido o version != 2 non usare routing catalog-dependent
e non produrre crash o stack trace.

Crea scripts/test-routing-engine.mjs e fixture runtime per tutti gli eval analyst
7-13 e orchestrator 6-11, più regressioni preesistenti.
Esegui i casi intent-only con neutralRoot.
Verifica skill primaria, insieme consentito, intent, priorità, lock, suppression,
anti-pattern, esclusioni e ranking.

Aggiorna guida e governance matrix:
- build-routing-catalog.mjs genera il catalogo;
- generate-codex-hooks.js genera la configurazione hook;
- UserPromptSubmit è verificato su Codex, non equivalente su Antigravity.

Non creare skill, agenti, schema MCP o dipendenze.
Non modificare manualmente file generati.
Non inglobare drift agenti.

Esegui tutte le validazioni della specifica.
Ricorda che routing-catalog.json è ignorato da Git:
refresh catalogo sì, restart MCP no.

Non creare commit o PR.

Chiudi con file, comandi, diagnostica routing, tabella smoke, catalog version/status,
drift, checklist PR, rischio cross-host, schema MCP e restart.
```

---

## 18. Cosa fare in caso di conflitto con il repository corrente

Se il repository è cambiato rispetto alla baseline:

1. preservare le nuove regole più restrittive;
2. non ripristinare contenuti rimossi intenzionalmente;
3. adattare gli inserimenti alla struttura corrente;
4. non creare path alternativi senza evidenza;
5. documentare:
   - conflitto;
   - file/versione osservata;
   - impatto;
   - adattamento minimo proposto.

Fermarsi soltanto se il conflitto cambia:

- routing canonico;
- ownership delle skill;
- policy agenti;
- formato eval;
- strumenti di generazione;
- sicurezza del source recovery;
- distinzione tra source e target;
- semantica di `project_path` o `save_path`;
- capacità di separare drift preesistente e modifiche correnti.

La dichiarazione `rework` nella guida, da sola, non autorizza il cambio del branch target `master`.

---

## 19. Provenienza del contenuto incorporato

Il materiale originario era composto da:

- `legacy-migration/SKILL.md`;
- `legacy-migration/references/deobfuscation-technique.md`.

SHA-256 archivio analizzato:

`a5a932e080438b1782e3a362dfeb2bcb6d19b0e27e5f1fe27624de8f9a6525c0`

Tutti i requisiti utili sono stati normalizzati e incorporati in questo documento. Le parti non importate sono state escluse intenzionalmente perché in conflitto con la governance del repository:

- trigger globale su ogni singola fase;
- implementer paralleli nello stesso progetto;
- policy modelli locale;
- uso di `eval` sui token;
- test non qualificati sul sistema live;
- manipolazione dello stato di lavoro corrente per simulare fresh install.

---

## 20. Esito atteso

Al termine non deve esistere una nuova skill `legacy-migration`.

Il repository deve disporre di:

- workflow end-to-end nell'orchestrator;
- inventory, source recovery e parity read-only nell'analyst;
- source recovery sicuro;
- catalogo routing schema v2;
- motore puro e diagnosticabile;
- intent con priorità `300/200/100/0`;
- azioni operative distinte dalle citazioni nominali;
- negazione locale e boundary-aware;
- suppression soltanto con priorità strettamente superiore;
- anti-pattern estratti solo da sezioni dedicate;
- esclusioni anti-pattern deterministiche;
- catalogo mancante/obsoleto gestito conservativamente;
- test puri del motore;
- smoke hook sugli eval completi;
- regressioni preesistenti preservate;
- alias source/target/evidence mappati ai parametri canonici;
- nessuna modifica agli schema MCP;
- nessuna nuova skill o agente;
- refresh catalogo documentato;
- restart MCP non richiesto;
- compatibilità Codex dichiarata e parità Antigravity non promessa;
- gestione drift agenti;
- documentazione e checklist PR aggiornate;
- nessuna dipendenza dallo ZIP originario.

Questo documento è il deliverable canonico finale. Il passo successivo è l'implementazione e poi la review `spec-compliance` del diff, non un'altra riscrittura della specifica.