# Analisi tecnica — Estensione di `mcp-coldfusion-developer` per migrazioni ad Adobe ColdFusion 2025 Repository: `sophiadeveloper/mcp-servers` Branch: `master` Baseline: `5b237489f670aa52914ee0cc9861b27e12e9ad1e` Data analisi: `2026-09-14` Formato: documento di analisi tecnica Markdown Modalità: read-only; nessuna modifica applicata al repository ## Sintesi esecutiva L'integrazione è tecnicamente fattibile e la scelta raccomandata è **estendere la skill esistente `mcp-coldfusion-developer`**, non creare una skill separata dedicata a ColdFusion 2025. La baseline analizzata mostra che `mcp-coldfusion-developer` possiede già: - routing specialistico per CFML; - una modalità `Cross-Version Migration`; - reference dedicate a Provider/Consumer e tracking della migrazione; - script Node.js con test unitari/E2E per validare il workspace neutrale; - regole permanenti che impongono lint iniziale, fix solo su richiesta esplicita e compatibilità legacy. La modalità cross-version attuale risolve però un problema diverso: **trasporto controllato di funzionalità o file tra versioni/branch/varianti**. Non contiene un modello target-version-aware per individuare e correggere incompatibilità del runtime ColdFusion. Nella baseline non risulta una reference CF2025 specifica né uno scanner dedicato alle incompatibilità CF2025. La proposta è quindi introdurre una modalità specializzata, concettualmente denominata **ColdFusion 2025 Compatibility Migration Mode**, composta da: 1. una reference CF2025 caricata solo quando il target è Adobe ColdFusion 2025; 2. una matrice di compatibilità cumulativa dipendente dalla versione sorgente; 3. uno scanner deterministico read-only per `.cfm` / `.cfc` e pattern di configurazione rilevanti; 4. una classificazione delle remediation in `SAFE_AUTOFIX`, `CONTEXTUAL_FIX`, `SEMANTIC_REWRITE`, `MANUAL_BLOCKER`; 5. provenienza esplicita di ogni regola (`Adobe`, `TESISQUARE`, `legacy internal`); 6. lint, re-scan e validazioni mirate dopo qualsiasi modifica; 7. fix automatici esclusivamente quando esplicitamente richiesti, coerentemente con la skill corrente. Le fonti interne fornite sono una buona base ma **non sono sufficienti, da sole, come knowledge generica CF2025**. Il confronto con la documentazione Adobe aggiornata evidenzia infatti rimozioni CF2025 non presenti nella sezione Platform 8.0 allegata, tra cui Axis1, `ThreadTerminate`, l'algoritmo `CFMX_COMPAT`, `cfschedule.requestTimeOut` e varie API/tag legacy. Inoltre alcune indicazioni storiche interne diventano errate se applicate senza contesto di versione: ad esempio la guida legacy propone di riabilitare Axis1 per versioni precedenti, mentre Adobe lo dichiara rimosso in ColdFusion 2025. La conclusione è pertanto: > **fattibilità alta**, con necessità di separare il workflow generico di migrazione dalla knowledge di compatibilità runtime, rendere le regole version-aware e trattare i regex allegati come ausili di detection/remediation controllata, non come trasformazioni globali intrinsecamente sicure. **Esito quality gate: `PASS_CON_RISCHI`.** Il piano è implementabile e coerente con la baseline osservata; i commit Platform interni citati negli allegati sono stati successivamente verificati, mentre restano da validare il comportamento runtime su un'istanza CF2025 e i casi semantici di trasformazione. ### Aggiornamento implementativo — evidenze Platform verificate I due commit interni precedentemente non disponibili sono stati ispezionati nel monorepo Platform senza cambiare branch o working tree: - `cc81d0e79616006764fd5d786f1cc02290c48023` introduce l'encoding dei singoli valori sostituiti tramite `encodeItems` / `escapeSingleItems` e rimuove il wrapper `HTMLEditFormat(maskParse(...))` da `header.cfc`; - `d07112fdd2abb9437271331130e85ad659765514` limita l'encoding di `xgrid_common.cfc` alle colonne query con metadata `varchar` o `nvarchar`. Lo scanner copre ora questi delta con le regole path-aware `TS25-016`, `TS25-017` e `TS25-018`, classificate `CONTEXTUAL_FIX` con provenienza `TESISQUARE-Platform`. La copertura e' intenzionalmente read-only: i diff costituiscono evidenza sufficiente per una remediation guidata, non per un autofix generalizzabile. Resta invariato il rischio runtime: `new query()` e `new http()` continuano a essere `SEMANTIC_REWRITE` e non possono essere certificati senza test applicativi su Adobe ColdFusion 2025. Il bridge locale configurato su `http://localhost:8500/mcp_agent.cfm` non risultava raggiungibile durante questa integrazione. --- ## Problema e obiettivo ### Problema La skill corrente può supportare una migrazione tra versioni del prodotto, ma non dispone di un contratto esplicito per rispondere in modo deterministico a richieste del tipo: - “porta questa codebase da CF2021 a CF2025”; - “verifica se questo modulo è compatibile con CF2025”; - “applica le breaking change necessarie per CF2025”; - “individua API rimosse/deprecate che bloccano il passaggio a CF2025”; - “esegui solo i fix meccanici sicuri e segnala quelli semantici”. Senza una modalità specializzata, l'agente dovrebbe ricostruire ogni volta: - quali regole siano obbligatorie; - quali regole siano cumulative in base alla versione sorgente; - quali indicazioni TESISQUARE prevalgano; - quali breaking change siano realmente rimosse dal runtime CF2025; - quali sostituzioni possano essere automatiche e quali richiedano comprensione del codice; - quali workaround storici siano ormai invalidi nel target 2025. ### Obiettivo Potenziare `mcp-coldfusion-developer` affinché possa eseguire un **assessment statico e una migrazione guidata del codice verso Adobe ColdFusion 2025**, preservando: - compatibilità legacy; - policy TESISQUARE; - separazione tra detection e modifica; - provenienza delle regole; - comportamento read-only per assessment; - modifica solo se esplicitamente richiesta; - validazione finale proporzionata al rischio. --- ## Comportamento attuale e comportamento atteso ### Comportamento attuale osservato Alla baseline analizzata: - `skills/mcp-coldfusion-developer/SKILL.md` include nel frontmatter le “controlled cross-version migration workflows”; - la tabella `Quick Routing` contiene la voce `Migrazione cross-version`; - `references/cross-version-migration.md` definisce una directory neutrale e ruoli Provider/Consumer; - il workflow cross-version è dichiarato **product-agnostic**; - la directory `scripts/` contiene: - `validate-migration-workspace.js`; - `validate-migration-workspace.test.js`; - `e2e-validate-migration-workspace.test.js`; - la skill non presenta, nella baseline consultata, uno scanner CF2025 dedicato; - una precedente analisi tecnica nel repository definisce esplicitamente la cross-version migration come estensione generica e non hardcoded su versioni o prodotti. Questo assetto è corretto per la migrazione funzionale, ma non copre in modo sufficiente la **compatibilità del runtime target**. ### Comportamento atteso Quando l'utente indica `target = ColdFusion 2025`, la skill dovrebbe: 1. identificare obbligatoriamente la versione ColdFusion sorgente, quando nota o ricavabile; 2. caricare la reference CF2025; 3. costruire il ruleset cumulativo applicabile alla coppia `source -> 2025`; 4. eseguire assessment statico prima di qualsiasi fix; 5. classificare ogni finding per severità e tipo di remediation; 6. distinguere regole Adobe generiche da regole TESISQUARE/Platform; 7. proporre o applicare solo remediation compatibili con il livello di rischio; 8. eseguire lint e nuovo scan; 9. produrre un riepilogo di blocker residui e verifiche runtime necessarie. La modalità CF2025 deve poter essere usata: - **standalone**, per aggiornare il runtime della stessa codebase; - **in composizione con Cross-Version Migration**, quando contemporaneamente si porta una funzionalità da una versione/branch a un target che gira su CF2025. --- ## Scope ### In scope - codice CFML `.cfm` / `.cfc`; - pattern di compatibilità staticamente identificabili; - funzioni/tag/attributi rimossi o incompatibili; - servizi CFC legacy; - API Java note quando esplicitamente documentate dalle fonti interne; - regole cumulative di migrazione contenute nella guida TESISQUARE allegata; - regole CF2025 documentate ufficialmente da Adobe; - regole specifiche Platform 8.0 fornite dall'utente; - classificazione automatica/manuale della remediation; - scanner deterministico; - test del ruleset/scanner; - integrazione nel routing della skill. ### Fuori scope - installazione/configurazione del server ColdFusion; - modifica di CF Admin; - deploy, cutover o rollback; - esecuzione runtime su ambienti reali; - aggiornamento database; - modifica di repository o branch in questa analisi; - verifica dei ticket Mantis citati negli allegati, non accessibili direttamente; - modifica o cherry-pick dei commit Platform interni; la loro verifica read-only e' stata eseguita successivamente sul monorepo locale; - garanzia di equivalenza funzionale senza test runtime/applicativi. --- ## Componenti coinvolti ### Componenti esistenti da estendere | Componente | Stato baseline | Ruolo proposto | |---|---|---| | `skills/mcp-coldfusion-developer/SKILL.md` | Presente | Aggiungere trigger/routing CF2025 mantenendo il file compatto | | `references/cross-version-migration.md` | Presente | Restare generico; non inglobare le regole CF2025 | | `references/migration-provider.md` / `migration-consumer.md` | Presenti | Usabili se CF2025 è parte di una migrazione cross-version | | `scripts/validate-migration-workspace.js` | Presente | Non riusare come scanner CFML; responsabilità diversa | | `evals/` | Presente | Aggiungere eval mirati per routing e classificazione CF2025 | | routing catalog | Generato dal repository | Da rigenerare se cambia il trigger/intent della skill | ### Nuovi componenti raccomandati Nomi proposti, da confermare in implementazione: ```text skills/mcp-coldfusion-developer/ ├── SKILL.md ├── references/ │ ├── coldfusion-2025-migration.md │ └── coldfusion-version-compatibility.md └── scripts/ ├── scan-cf2025-compatibility.js └── scan-cf2025-compatibility.test.js ``` Non è necessario introdurre un nuovo MCP server. --- ## Fonti consultate ### Fonti fornite dall'utente 1. `breaking changes · Wiki · tesisquare-platform-release _ 8.0-app · GitLab.html` - snapshot della wiki Platform 8.0; - sezione “ColdFusion compatibility”; - fonte fornita dall'utente, non letta direttamente dal GitLab interno. 2. `proc0064_app_to_cf10-_migration_guide.md` - guida storica TESISQUARE dalla migrazione CF8/9 fino a CF2025; - contiene regole cumulative, troubleshooting e riferimenti a ticket/commit interni; - fonte fornita dall'utente. ### Repository `sophiadeveloper/mcp-servers` Baseline `5b237489f670aa52914ee0cc9861b27e12e9ad1e`: - `skills/mcp-coldfusion-developer/SKILL.md`; - `skills/mcp-coldfusion-developer/references/cross-version-migration.md`; - `skills/mcp-coldfusion-developer/references/*`; - `skills/mcp-coldfusion-developer/scripts/*`; - `docs/analisi-tecniche/analisi-tecnica-potenzialmento-skill-cf-developer-sviluppo-cross-version-migration.md`; - `docs/pr-checklist-mcp.md`; - `scripts/build-routing-catalog.mjs`. ### Fonti ufficiali Adobe Consultazione: `2026-09-14`. 1. **Deprecated Features — Adobe ColdFusion** URL: https://helpx.adobe.com/coldfusion/deprecated-features.html Stato: fonte ufficiale primaria, aggiornata al 18 maggio 2026. Uso: rimozioni/deprecazioni CF2025, tra cui CFMX_COMPAT, ThreadTerminate, Axis1, script-based CFC, `cfschedule.requestTimeOut`, `HTMLEditFormat`, `ParameterExists`. 2. **HTMLEditFormat — Adobe ColdFusion CFML Reference** URL: https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-h-im/htmleditformat.html Stato: fonte ufficiale primaria. Uso: conferma rimozione in CF2025 e raccomandazione `EncodeForHTML`. 3. **cfheader — Adobe ColdFusion CFML Reference** URL: https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-tags/tags-g-h/cfheader.html Stato: fonte ufficiale primaria. Uso: conferma rimozione dell'attributo `statusText` in CF2025. 4. **ParameterExists — Adobe ColdFusion CFML Reference** URL: https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-m-r/parameterexists.html Stato: fonte ufficiale primaria, ma pagina specifica storicamente meno aggiornata della matrice generale. Uso: raccomandazione `IsDefined`. La matrice `Deprecated Features` aggiornata chiarisce la rimozione in CF2025. 5. **Script Functions Implemented as CFCs / Function summary — Adobe** URL: https://helpx.adobe.com/coldfusion/cfml-reference/script-functions-implemented-as-cfcs/function-summary.html Stato: fonte ufficiale primaria. Uso: `http`, `query`, `storedproc` e altri servizi CFC erano già deprecati dal 2018; la matrice `Deprecated Features` indica la rimozione del supporto script-based CFC in CF2025. 6. **URLEncodedFormat — Adobe ColdFusion CFML Reference** URL: https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-t-z/urlencodedformat.html Stato: fonte ufficiale primaria, aggiornata al 18 maggio 2026. Uso: Adobe raccomanda `EncodeForURL` per nuovo codice, ma `URLEncodedFormat` non è presentata come rimossa. 7. **EncodeForURL — Adobe ColdFusion CFML Reference** URL: https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-e-g/encodeforurl.html Stato: fonte ufficiale primaria, aggiornata al 18 maggio 2026. Uso: verifica della firma; secondo argomento `canonicalize`, non `charset`. 8. **GenerateSecretKey — Adobe ColdFusion CFML Reference** URL: https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-e-g/generatesecretkey.html Stato: fonte ufficiale primaria. Uso: firma `GenerateSecretKey(algorithm [,keysize])`; la pagina non documenta esplicitamente la variazione del default citata dalla fonte TESISQUARE. ### Limiti delle fonti - Mantis non è stato consultato. - GitLab TESISQUARE non è stato consultato direttamente. - I commit Platform `cc81d0e7` e `d07112fd`, inizialmente solo citati dalla guida allegata, sono stati successivamente verificati nel monorepo locale. - Nessun ambiente CF2025 è stato eseguito. - Non sono stati effettuati test funzionali o runtime. --- ## Evidenze osservate ### 1. La skill attuale è già il contenitore corretto Il frontmatter di `mcp-coldfusion-developer` include esplicitamente le migrazioni cross-version. La skill possiede già reference e script dedicati al dominio. La creazione di una nuova skill CF2025 introdurrebbe: - duplicazione di routing; - sovrapposizione sulla stessa codebase CFML; - doppia gestione di lint e handoff; - rischio di divergenza tra regole generiche e version-specific. **Evidenza:** baseline `SKILL.md` e struttura della directory della skill. **Conclusione:** estensione della skill esistente. ### 2. Il workflow Cross-Version Migration non è un migration engine CFML `cross-version-migration.md` tratta: - directory neutrale; - Provider; - Consumer; - `touched-files.md`; - path target forniti dall'utente; - stati `TO ADD`, `TO MERGE`, `ADDED`, `MERGED`. Non definisce una matrice di breaking change del runtime. **Conclusione:** la modalità CF2025 deve essere una capability separata ma componibile, non un'estensione semantica del file `cross-version-migration.md`. ### 3. Le regole Platform 8.0 coprono un nucleo CF2025 utile La fonte Platform 8.0 fornita dall'utente identifica almeno: - `HtmlEditFormat` rimosso; - `statusText` rimosso; - `parameterExists` rimosso; - `query` service rimosso; - variazione `generateSecretKey`; - `UrlEncodedFormat` sostituito secondo policy Platform; - `new http` sostituito con `cfhttp`. Queste regole sono adatte come **profilo TESISQUARE/Platform**, non come unica knowledge Adobe CF2025. ### 4. La guida storica contiene regole cumulative indispensabili `proc0064...` contiene, tra le altre: - collisioni con funzioni custom (`cflog`, `cfdump`, `cfthrow`, ecc.); - attributi legacy di `cflog`; - normalizzazione `cfsqltype`; - problematiche Java/POI; - `getTimeZone`; - variazioni `hash`; - `HSSFDateUtil` -> `DateUtil`; - interventi specifici `maskParse`; - interventi `xgrid_common.cfc`. Questo supporta l'adozione di una **matrice source-version-aware**, invece di una lista CF2025 piatta. ### 5. Esistono conflitti temporali che richiedono precedence rules #### Axis1 La guida storica indica, per vecchie migrazioni, la possibilità di configurare Axis1 in ColdFusion Administrator. La documentazione Adobe aggiornata indica **Axis1 rimosso in ColdFusion 2025**. Quindi una knowledge non versionata potrebbe suggerire una remediation ormai impossibile. #### `cfschedule.requestTimeOut` La guida storica descrive un workaround applicativo/configurativo. Adobe dichiara l'attributo `requestTimeOut` di `cfschedule` rimosso in CF2025. Anche qui la skill deve conoscere target e versione della regola. **Conclusione:** una regola legacy deve poter essere marcata come `superseded` da una regola target-specific più recente. ### 6. Adobe documenta altre incompatibilità CF2025 non presenti nel nucleo Platform allegato La matrice Adobe aggiornata include almeno: - rimozione dell'algoritmo `CFMX_COMPAT`, con impatto su funzioni crypto/random; - JDK 21 e rimozione del supporto collegato a `Thread.stop()`; - rimozione di `ThreadTerminate`; - rimozione Axis1; - rimozione del supporto script-based CFC, inclusi esempi `query` e `storedproc`; - rimozione di `cfschedule.requestTimeOut`; - rimozione di vari tag/UI legacy; - rimozione `HTMLEditFormat`; - rimozione `ParameterExists`. Per una skill generica di migrazione codice CF2025, almeno le voci staticamente rilevabili devono entrare nel ruleset. --- ## Matrice iniziale delle regole | Regola | Evidenza interna | Evidenza Adobe | Classe raccomandata | Nota | |---|---|---|---|---| | `HTMLEditFormat()` -> `EncodeForHTML()` | Platform 8.0 | Rimossa CF2025; Adobe raccomanda `EncodeForHTML` | `SAFE_AUTOFIX` con guardie | Evitare regex cieco su espressioni annidate | | `cfheader statusText` | Platform 8.0 | Rimossa CF2025 | `SAFE_AUTOFIX` | Rimozione attributo, verificare sintassi residua | | `ParameterExists()` -> `IsDefined()` | Platform 8.0 | Rimossa CF2025; Adobe raccomanda `IsDefined` | `CONTEXTUAL_FIX` | Autofix solo per riferimenti semplici | | `new query()` | Platform 8.0 | Script-based CFC rimossi CF2025 | `SEMANTIC_REWRITE` | Migrare a `QueryExecute()` secondo standard locale | | `new http()` | Platform 8.0 | `http` è service CFC deprecato dal 2018; rimozione generica dei service CFC supporta il rischio | `SEMANTIC_REWRITE` | Non trattare come semplice rename | | `generateSecretKey("AES")` -> `(...,128)` | Platform 8.0 | Firma con `keysize` confermata; cambio default non esplicitato nella pagina funzione | `CONTEXTUAL_FIX` | Regola TESISQUARE; richiede test crypto | | `URLEncodedFormat()` -> `EncodeForURL()` | Platform 8.0 | Adobe raccomanda `EncodeForURL`, non dichiara rimozione | `CONTEXTUAL_FIX` | Il secondo argomento ha semantica diversa | | `CFMX_COMPAT` | Non nel nucleo Platform allegato | Rimosso CF2025 | `MANUAL_BLOCKER` | Impatto crypto/random, non autofixabile genericamente | | `ThreadTerminate` | Non nel nucleo Platform allegato | Rimosso CF2025 | `MANUAL_BLOCKER` | Richiede redesign del controllo thread | | Axis1 | Guida storica lo gestisce per vecchie versioni | Rimosso CF2025 | `MANUAL_BLOCKER` | La remediation storica non è valida sul target | | `cfschedule.requestTimeOut` | Guida storica contiene workaround | Rimosso CF2025 | `MANUAL_BLOCKER` / config review | Regola storica superseded | | `HSSFDateUtil` | Guida storica CF2023 HF15 | Dipendenza POI, non regola CF2025 primaria | `CONTEXTUAL_FIX` cumulativo | Da includere se source pre-correzione | | `hash()` default | Guida storica CF2021 HF14 / 2023 HF8 | CF2025 rimuove anche `CFMX_COMPAT` | `CONTEXTUAL_FIX` cumulativo | Richiede preservazione output atteso | | `maskParse` | Guida interna CF2025 | Commit Platform `cc81d0e7` verificato | `CONTEXTUAL_FIX` / `TS25-016` e `TS25-017` | Detection limitata ai path Platform | | `xgrid_common.cfc` encoding | Guida interna CF2025 | Commit Platform `d07112fd` verificato | `CONTEXTUAL_FIX` / `TS25-018` | Non generalizzare a progetti non Platform | --- ## Rischi tecnici delle sostituzioni automatiche ### Regex `HTMLEditFormat` Il pattern allegato: ```regex htmleditformat\(([^\)]+)\) ``` è utile per casi semplici ma non è un parser. Espressioni con chiamate annidate possono produrre match incompleti. Esempio concettuale: ```cfml htmlEditFormat(formatMessage(getText(key))) ``` La detection può usare regex/tokenizzazione, ma l'autofix dovrebbe essere limitato a pattern sintatticamente sicuri o validato tramite parser/linter. ### `ParameterExists` -> `IsDefined` La sostituzione: ```text parameterexists(X) -> isdefined("X") ``` è sicura solo quando `X` rappresenta direttamente un path di variabile compatibile con la semantica string-based di `IsDefined`. Casi dinamici o espressioni complesse devono essere classificati `CONTEXTUAL_FIX`. ### `URLEncodedFormat` -> `EncodeForURL` La fonte Adobe aggiornata mostra: ```text URLEncodedFormat(string [, charset]) EncodeForURL(inputString [, canonicalize]) ``` Il secondo parametro non ha la stessa semantica. Quindi il search/replace globale del solo nome funzione può essere errato per chiamate a due argomenti. Regola proposta: - un argomento: trasformazione candidata automatica; - due argomenti: review obbligatoria; - verificare anche la differenza di encoding degli spazi (`EncodeForURL` documenta `+`, non `%20`). ### `new query` -> `QueryExecute` Una query service può contenere: - datasource; - SQL; - parametri; - timeout; - cached options; - return/result metadata; - catena `setSQL`, `addParam`, `execute`, `getResult`, `getPrefix`. Non esiste un replace globale affidabile. La skill deve: 1. ricostruire contratto della query; 2. preservare parametrizzazione; 3. trasformare a `QueryExecute(sql, params, options)`; 4. preservare eventuali metadati `result`; 5. richiedere test su output e side effect. ### `new http` -> `cfhttp` Analogo problema: - method; - URL; - headers; - body; - parametri; - auth; - timeout; - proxy; - binary/text handling; - response prefix/result. La trasformazione deve essere agentica e verificata, non regex-only. ### `GenerateSecretKey` La regola interna prescrive la lunghezza AES 128 esplicita. La documentazione Adobe conferma il parametro `keysize`, ma la pagina consultata non documenta esplicitamente il cambio del default. Questa regola deve quindi essere marcata: - `source = TESISQUARE Platform 8.0`; - `mandatoryForPlatform = true`; - `adobeDirectEvidence = partial`. La validazione deve includere compatibilità con dati cifrati/decifrati già persistiti quando pertinente. --- ## Modello di regola raccomandato Per evitare knowledge puramente narrativa, ogni regola dovrebbe avere almeno questi attributi concettuali: ```yaml id: CF25-XXX target: "2025" source_versions: min: "..." max: "..." scope: code|config|runtime|platform severity: blocker|mandatory|recommended|informational provenance: - adobe - tesisquare status: removed|deprecated|behavior-change|platform-policy detection: exact|regex|semantic remediation: safe-autofix|contextual|semantic|manual validation: - lint - rescan - targeted-test supersedes: - ... ``` Non è necessario che il formato finale sia YAML; il punto architetturale è rendere espliciti: - target; - versione sorgente; - provenienza; - severità; - automazione; - validazione; - precedence. --- ## Precedence delle fonti e delle regole La skill deve evitare sia di ignorare la policy interna sia di applicare workaround storici incompatibili con il runtime target. Precedence proposta in caso di conflitto: 1. **rimozione/contratto target-runtime Adobe aggiornato**, per stabilire cosa esiste o non esiste in CF2025; 2. **regola TESISQUARE Platform target-specific**, per stabilire il pattern applicativo certificato internamente; 3. **guida legacy interna**, solo se compatibile con il target; 4. **euristica agentica**, solo quando nessuna fonte normativa chiude il caso. Esempio: - vecchia guida: abilitare Axis1; - Adobe CF2025: Axis1 rimosso; - esito: `BLOCKER`, non applicare il workaround storico. La skill deve riportare il conflitto, non nasconderlo. --- ## Matrice versionale raccomandata La migrazione non deve essere interpretata come “applica solo le novità 2025”. Schema concettuale: | Versione sorgente | Ruleset minimo da considerare | |---|---| | CF8/9 | legacy CF10+ + 2016 + 2018 + 2021 + 2023 + 2025 | | CF10 | post-CF10 + 2016 + 2018 + 2021 + 2023 + 2025 | | CF2016 | 2018 + 2021 + 2023 + 2025 | | CF2018 | 2021 + 2023 + 2025 | | CF2021 | 2023 + 2025 | | CF2023 | 2025 | La tabella non implica che ogni regola intermedia sia ancora attiva: la precedence deve eliminare regole superseded. --- ## Architettura proposta ```mermaid flowchart LR A["Input: repository + source CF + target CF2025"] --> B["CF2025 assessment"] B --> C["Load cumulative ruleset"] C --> D["Static scanner"] D --> E["Classify findings"] E --> F1["SAFE_AUTOFIX"] E --> F2["CONTEXTUAL_FIX"] E --> F3["SEMANTIC_REWRITE"] E --> F4["MANUAL_BLOCKER"] F1 --> G["Fix only if explicitly requested"] F2 --> G F3 --> G F4 --> H["Handoff / manual decision"] G --> I["Lint + targeted validation + re-scan"] I --> J["Residual blockers report"] ``` --- ## Piano tecnico proposto ### Milestone 1 — Knowledge e routing CF2025 #### Obiettivo Rendere la skill selezionabile esplicitamente per: - upgrade CFML a CF2025; - compatibility assessment CF2025; - remediation di breaking change CF2025. #### Attività - aggiornare in modo conservativo la `description` di `SKILL.md`; - aggiungere una riga a `Quick Routing`; - creare `references/coldfusion-2025-migration.md`; - mantenere `cross-version-migration.md` generico; - documentare la composizione tra le due modalità. #### Vincolo repository La checklist del repository stabilisce che, se cambiano skill/intenti: ```bash node scripts/build-routing-catalog.mjs ``` e richiede inoltre i test di routing previsti dalla checklist del repository. #### Criterio di completamento Prompt CF2025 instradati a `mcp-coldfusion-developer` senza degradare i trigger esistenti. --- ### Milestone 2 — Ruleset version-aware #### Obiettivo Trasformare le fonti allegate e Adobe in regole esplicite e verificabili. #### Attività - registrare provenienza; - registrare target/source range; - classificare severità; - definire regole superseded; - separare `generic Adobe` da `TESISQUARE Platform`; - includere almeno tutte le regole obbligatorie già documentate da Platform 8.0; - includere blocker CF2025 ufficiali staticamente rilevabili. #### Criterio di completamento Ogni regola ha fonte, livello di automazione e validazione associata. --- ### Milestone 3 — Scanner deterministico #### Obiettivo Produrre assessment ripetibile senza dipendere dalla sola memoria del modello. #### Interfaccia concettuale ```bash node skills/mcp-coldfusion-developer/scripts/scan-cf2025-compatibility.js \ --source-version 2021 \ ``` #### Output raccomandato ```text CF2025 COMPATIBILITY ASSESSMENT BLOCKER [CF25-...] ... SEMANTIC_REWRITE [CF25-...] ... CONTEXTUAL_FIX [CF25-...] ... SAFE_AUTOFIX [CF25-...] ... Summary: - blocker: N - semantic: N - contextual: N - safe: N ``` #### Regole dello scanner - default read-only; - nessuna modifica file; - ignora vendor/build/output configurabili; - riporta file e posizione; - non stampa valori sensibili; - exit code differenziabile tra `clean`, `findings`, `error`; - output stabile e testabile. #### Criterio di completamento Fixture note producono finding deterministici senza falsi autofix sui casi negativi previsti. --- ### Milestone 4 — Remediation controllata #### Obiettivo Consentire alla skill di applicare modifiche solo quando l'utente lo chiede esplicitamente. #### Policy `SAFE_AUTOFIX` - sostituzione/rimozione strutturalmente deterministica; - lint obbligatorio. `CONTEXTUAL_FIX` - l'agente deve leggere il contesto; - nessun bulk replace cieco. `SEMANTIC_REWRITE` - trasformazione per singolo call site; - preservazione parametri, risultati e side effect; - test mirato. `MANUAL_BLOCKER` - nessuna modifica automatica; - produrre handoff tecnico. #### Criterio di completamento La skill non applica automaticamente fix classificati oltre il livello consentito. --- ### Milestone 5 — Quality gate e regression protection #### Obiettivo Rendere l'estensione manutenibile. #### Test minimi - unit test scanner per ogni regola; - negative test; - casi annidati; - commenti e stringhe che non devono generare falsi positivi; - case-insensitive CFML; - file `.cfm` e `.cfc`; - chiamate con argomenti opzionali; - regression test sulle regole superseded; - eval del routing; - test di routing repository; - lint CFML sui file migrati; - re-scan post-fix. #### Criterio di completamento Nessun blocker statico irrisolto viene marcato implicitamente come “migrato”. --- ## Criteri di accettazione ### Routing - richieste esplicite “ColdFusion 2025”, “CF2025 migration”, “upgrade CFML to 2025” selezionano la skill corretta; - le richieste cross-version generiche continuano a usare la modalità esistente; - la modifica non crea una seconda skill sovrapposta. ### Assessment - la versione sorgente è registrata o dichiarata non nota; - lo scanner opera read-only; - ogni finding include ID, categoria, file/posizione e provenienza; - le regole Adobe e TESISQUARE sono distinguibili; - regole legacy superseded non vengono suggerite come remediation valida. ### Remediation - `HTMLEditFormat` semplice può essere classificato safe; - `statusText` semplice può essere classificato safe; - `ParameterExists` dinamico non viene autofixato; - `URLEncodedFormat` a due argomenti non viene trasformato ciecamente; - `new query` e `new http` non vengono gestiti come replace testuale globale; - blocker come Axis1/CFMX_COMPAT/ThreadTerminate richiedono handoff. ### Validazione - lint prima/dopo i fix; - re-scan finale; - test mirati sui call site semantici; - routing catalog rigenerato se cambia il trigger della skill; - test routing previsti dalla checklist repository eseguiti nell'implementazione. --- ## Validazioni consigliate ### Statiche 1. scanner su fixture sintetiche; 2. scanner su un repository CFML reale ma non modificato; 3. confronto conteggi con ricerca manuale campionaria; 4. lint su file campione; 5. re-scan dopo remediation. ### Funzionali Da eseguire su ambiente autorizzato CF2025, fuori da questa analisi: - query con parametri e result metadata; - chiamate HTTP con auth/header/body/binary; - output HTML encoding; - URL encoding con caratteri speciali e spazi; - encryption/decryption con chiavi esistenti; - scheduler; - integrazioni SOAP/webservice; - eventuali flussi thread; - export/import Excel se coinvolti da POI. ### Compatibilità Testare almeno: - caso nominale; - input null/empty quando rilevante; - chiamate con argomenti opzionali; - dati cifrati storici; - datasource diversi; - response HTTP non 2xx; - query senza righe / con più righe; - encoding non ASCII; - regressione su vecchi file che non contengono breaking change. --- ## Rischi e punti aperti ### RSK-01 — Regex presentati come search/replace possono sovra-correggere **Rischio:** alto se usati in bulk. **Mitigazione:** detection ampia, autofix stretto; test sintattici. ### RSK-02 — Fonti interne e Adobe hanno età/scopi differenti **Rischio:** applicare workaround storici a CF2025. **Mitigazione:** provenance e `supersedes`. ### RSK-03 — `GenerateSecretKey` richiede evidenza aggiuntiva La regola TESISQUARE è esplicita, ma la documentazione Adobe funzione consultata non spiega il cambio del default citato. **Azione:** conservare la regola come Platform-specific e validarla sui casi reali; non presentarla come fatto Adobe non verificato. ### RSK-04 — Applicazione contestuale dei commit Platform I diff `cc81d0e7` e `d07112fd` sono stati ispezionati e tradotti in detection path-aware. Restano dipendenze dal markup consentito e dai tipi restituiti dal datasource. **Azione:** mantenere le regole come `CONTEXTUAL_FIX`, senza autofix, e validare i call site applicativi prima della remediation. ### RSK-05 — Runtime non verificato Nessun comportamento è stato eseguito su CF2025. **Azione:** test applicativi su ambiente dedicato prima di certificare una migrazione. ### RSK-06 — Ambito Adobe più ampio del nucleo Platform La matrice Adobe include molte rimozioni UI/infrastrutturali. **Azione:** lo scanner deve coprire solo elementi staticamente rilevabili e materialmente pertinenti; evitare di trasformarsi in inventario indiscriminato del prodotto. --- ## Assunzioni - il repository target della modifica skill è `sophiadeveloper/mcp-servers`; - il branch di riferimento è `master`; - la baseline analizzata è il commit più recente osservato durante l'analisi; - la skill da estendere è `mcp-coldfusion-developer`; - gli allegati forniti dall'utente rappresentano policy/conoscenza interna da preservare, ma non sostituiscono la documentazione Adobe per stabilire disponibilità del runtime; - l'implementazione futura potrà modificare codice solo dietro richiesta esplicita, coerentemente con le regole della skill. --- ## Decisione tecnica ### Raccomandazione **Procedere con l'estensione di `mcp-coldfusion-developer`.** Non creare `mcp-coldfusion-2025`. La separazione raccomandata è: ```text mcp-coldfusion-developer ├── generic CFML development/debug ├── Cross-Version Migration Mode │ └── trasferimento controllato Provider/Consumer └── ColdFusion 2025 Compatibility Migration Mode ├── source-version matrix ├── Adobe + TESISQUARE rules ├── deterministic scanner ├── controlled remediation └── lint / tests / re-scan ``` ### Motivazione - ownership di dominio già corretta; - riduzione overlap routing; - riuso del lint/handoff esistente; - progressivo caricamento della knowledge; - possibilità di estendere in futuro a CF2027 senza duplicare skill; - migliore tracciabilità delle regole; - separazione tra compatibilità runtime e migrazione funzionale. --- ## Handoff implementativo L'implementazione dovrebbe partire dai seguenti deliverable: 1. `references/coldfusion-2025-migration.md`; 2. matrice versionale con provenance e supersede; 3. scanner read-only; 4. test scanner; 5. aggiornamento minimale di `SKILL.md`; 6. eval/routing test; 7. quality gate repository. I diff Platform-specific sono ora acquisiti e coperti da detection guidata; l'applicazione delle remediation resta contestuale e non automatica. La certificazione della migrazione di una codebase concreta richiederà sempre, oltre al re-scan statico, test applicativi su ColdFusion 2025. --- ## Confidenza | Area | Confidenza | Motivazione | |---|---|---| | Fattibilità dell'estensione skill | Alta | Struttura esistente già compatibile | | Scelta “estendere, non creare nuova skill” | Alta | Dominio e routing già presenti | | Regole `HTMLEditFormat`, `statusText`, `ParameterExists` | Alta | Confermate da Adobe CF2025 | | Rimozione script-based CFC/query | Alta | Confermata dalla matrice Adobe | | `new http` -> `cfhttp` come regola Platform | Medio-alta | Fonte interna esplicita; Adobe conferma deprecazione storica dei service CFC, ma la pagina specifica non è perfettamente allineata | | `URLEncodedFormat` -> `EncodeForURL` | Alta come raccomandazione, media come autofix | Firma/semantica secondo argomento differente | | `generateSecretKey("AES",128)` | Media | Regola interna esplicita; causa Adobe non documentata nella pagina funzione consultata | | `maskParse` / `xgrid_common.cfc` | Alta per detection, media per remediation | Commit sorgente verificati; equivalenza applicativa ancora da validare | | Assenza di regressioni runtime | Non valutabile | Nessuna esecuzione CF2025 | --- ## Quality gate Esito: **PASS_CON_RISCHI** - scope e baseline: coperti; - fonti interne/repository/web: distinte; - evidenze e inferenze: separate; - conflitti tra fonti: esplicitati; - compatibilità legacy: considerata; - regressioni e validazioni: definite; - dati sensibili: non riportati; - nessuna modifica a repository/sistemi esterni: eseguita; - rischi residui: espliciti. I rischi residui non bloccano la progettazione dell'estensione, ma impediscono di dichiarare “certificata” una migrazione concreta senza ulteriori evidenze e test runtime.