# Analisi tecnica implementativa — editing incrementale e sincronizzazione Markdown → DOCX Repository: `sophiadeveloper/mcp-servers` Branch: `master` Baseline: `407677463f1944ffc4d6c1051c0975bb0c4b12be` Data analisi: 30 luglio 2026 Formato: documento di analisi tecnica `.md` Stato: proposta implementativa read-only; nessuna modifica applicata al repository ## Sintesi esecutiva Il repository dispone già di una pipeline efficace per creare documenti DOCX a partire da Markdown tramite `document_convert`/Pandoc e di operazioni Word elementari tramite `word_document`. Manca però una capability affidabile per modificare un DOCX esistente in modo semantico e conservativo. Il caso d’uso prioritario è il seguente: 1. la documentazione tecnica nasce in uno o più file Markdown; 2. la prima versione DOCX viene generata dal Markdown; 3. il DOCX viene successivamente rifinito in Word, acquisendo formattazioni, commenti, revisioni, header/footer, copertine o contenuti editoriali; 4. il Markdown sorgente continua a evolvere; 5. oggi, per riportare le modifiche nel DOCX, occorre rigenerare il documento completo oppure intervenire tramite indici di paragrafo fragili; 6. la soluzione proposta permette di aggiornare direttamente nel DOCX soltanto i capitoli o le sezioni modificate, preservando il resto del package Word. La soluzione raccomandata è ibrida: - estendere `office-node` e il tool MCP `word_document` con operazioni semantiche di ispezione, editing per sezione e sincronizzazione da Markdown; - potenziare `mcp-office-expert` affinché scelga esplicitamente tra MCP e strumenti locali; - distribuire nel bundle della skill strumenti Node autocontenuti per ispezione e manipolazione OOXML diretta; - mantenere completa separazione runtime: la skill non importa file interni di `office-node` e `office-node` non dipende dai file installati con la skill; - introdurre eval dedicati per routing, scelta MCP/script, preservazione, conflitti e composizione con le altre skill. La skill DOCX pubblicata da Anthropic costituisce un riferimento tecnico per i pattern operativi, non una base di codice da copiare. Essa conferma tre principi rilevanti: un DOCX esistente va modificato a livello OOXML anziché ricreato con `docx-js`; il testo Word può essere frammentato in più run; ogni modifica deve essere seguita da validazione e, quando possibile, verifica visuale. I materiali Anthropic sono dichiarati proprietari: l’implementazione deve quindi essere clean-room, basata su specifiche OOXML pubbliche, librerie compatibili e test propri. Esito del quality gate analitico: **PASS_CON_RISCHI**. La direzione architetturale è definita; restano da validare in prototipo il formato del manifest di sincronizzazione, la fedeltà del trapianto di frammenti Markdown complessi e la compatibilità Word/LibreOffice. --- ## 1. Problema e obiettivo ### 1.1 Problema attuale La pipeline esistente è principalmente orientata alla produzione: ```text Markdown ↓ document_convert / Pandoc DOCX completo ``` Dopo la generazione iniziale, il DOCX può evolvere indipendentemente dal Markdown: - rifinitura manuale degli stili; - aggiunta di copertine, header e footer; - numerazione e impaginazione; - correzioni editoriali; - commenti e revisioni; - immagini ridimensionate o sostituite; - appendici o contenuti aggiunti direttamente in Word. Una nuova conversione completa Markdown → DOCX può perdere o alterare tali evoluzioni. Le operazioni Word attuali non risolvono il problema perché individuano il contenuto tramite indice numerico del paragrafo e, per `edit_paragraph`, eliminano i run esistenti sostituendoli con un singolo run. Questo approccio non è adatto a documenti complessi e può perdere formattazioni miste, hyperlink, bookmark, marker di commento o revisioni presenti nel paragrafo. ### 1.2 Obiettivo Introdurre una capability che permetta richieste naturali come: ```text Aggiorna nel DOCX il capitolo “Autenticazione” usando la versione corrente del Markdown, senza modificare gli altri capitoli. ``` oppure: ```text Aggiungi questo contenuto alla fine della sezione “Limitazioni”. ``` Il comportamento atteso è: ```text Markdown aggiornato + DOCX esistente ↓ analisi outline e mapping piano delle sole sezioni cambiate ↓ applicazione controllata nuovo DOCX con modifiche locali ↓ validazione strutturale e di preservazione DOCX aggiornato ``` ### 1.3 Risultato funzionale atteso La capability deve trasformare `mcp-office-expert` da semplice generatore/converter a editor strutturale di documenti Word esistenti, mantenendo: - il DOCX come artefatto editoriale persistente; - il Markdown come sorgente semantica delle sezioni collegate; - una sincronizzazione incrementale e verificabile; - la possibilità di intervento OOXML diretto quando il contratto MCP non copre il caso. --- ## 2. Scope e fuori scope ### 2.1 Scope Rientrano nello scope: 1. ispezione dell’outline di un DOCX; 2. identificazione robusta di capitoli e sezioni; 3. lettura del contenuto di una sezione; 4. sostituzione, append, prepend, inserimento, rinomina ed eliminazione di sezioni; 5. creazione di un piano di sincronizzazione Markdown → DOCX; 6. applicazione delle sole sezioni aggiunte, modificate, eliminate o spostate; 7. rilevamento delle modifiche concorrenti tra Markdown e DOCX; 8. preservazione delle parti non coinvolte; 9. salvataggio non distruttivo tramite `output_path`; 10. validazione del package DOCX; 11. strumenti OOXML bundled nella skill; 12. aggiornamento della skill `mcp-office-expert`; 13. aggiornamento del routing e delle compatibilità semantiche; 14. eval e smoke test dedicati; 15. estensione successiva a find/replace cross-run, immagini, commenti e revisioni. ### 2.2 Fuori scope iniziale Non rientrano nella prima milestone funzionale: - editing di file legacy `.doc`; - esecuzione o modifica di macro; - supporto completo a `.docm`; - merge automatico di conflitti semantici complessi; - fedeltà assoluta per ogni costrutto Word possibile; - modifica del DOCX originale come default; - ricostruzione completa del documento quando è sufficiente una patch locale; - dipendenza runtime tra skill e directory interna di `office-node`; - copia o derivazione del codice proprietario Anthropic; - introduzione di una seconda skill DOCX discoverable concorrente con `mcp-office-expert`. ### 2.3 Compatibilità legacy Le action esistenti di `word_document` devono rimanere disponibili: ```text read list_paragraphs create edit_paragraph insert_paragraph delete_paragraph ``` Il loro comportamento legacy non deve essere modificato implicitamente nella stessa milestone. La skill dovrà però evitare `edit_paragraph` per documenti complessi quando è disponibile l’editing section-aware. --- ## 3. Baseline ed evidenze osservate ### 3.1 `mcp-office-expert` La skill corrente: - dichiara `word_document`, `excel_document`, `pdf_document` e `document_convert`; - usa `list_paragraphs` prima delle modifiche Word; - propone `edit_paragraph`, `insert_paragraph` e `delete_paragraph`; - considera Pandoc il percorso per conversioni Markdown ↔ DOCX; - dispone già di helper locali in `skills/mcp-office-expert/tools/`; - stabilisce che gli helper locali non sostituiscono l’API MCP nei workflow normali; - include un catalogo machine-readable degli helper; - riconosce già la sinergia con `mcp-docs-navigator`, `mcp-database-expert` e `mcp-technical-analyst`. Evidenze: - `skills/mcp-office-expert/SKILL.md`, righe 12-27, 44-76, 84-111; - `skills/mcp-office-expert/tools/catalog.json`. ### 3.2 `office-node` `office-node` utilizza già: - `docx` per la creazione di nuovi documenti; - `PizZip` per aprire il package DOCX; - `@xmldom/xmldom` per analizzare `word/document.xml`; - `mammoth` per l’estrazione testuale; - Pandoc per conversioni general-purpose. Il tool `word_document` espone soltanto azioni basate su documento intero o indice del paragrafo. L’implementazione attuale di `edit_paragraph`: 1. apre il DOCX; 2. individua il paragrafo tramite indice; 3. elimina tutti i nodi `w:r`; 4. crea un solo nuovo run; 5. riscrive `word/document.xml`; 6. salva sul file di input. Questa implementazione è sufficiente per modifiche elementari, ma non garantisce la preservazione della struttura interna del paragrafo. Evidenze: - `office-node/index.js`, righe 295-334; - `office-node/index.js`, righe 1621-1664 circa per lo schema `word_document`; - `office-node/index.js`, righe 1908-2043 circa per le action Word; - `office-node/package.json`. ### 3.3 Test ed eval correnti La suite smoke di `office-node` verifica: - schema MCP; - prompt MCP; - artifact registry; - scrittura Excel; - export PDF; - compatibilità di base. Non contiene casi specifici per editing strutturale DOCX, outline, preservazione, sincronizzazione o OOXML diretto. Gli eval di `mcp-office-expert` coprono attualmente: - Word edit controllato in forma generale; - report Excel; - export PDF e handoff. Non coprono: - scelta tra MCP e script bundled; - aggiornamento per capitolo; - sincronizzazione Markdown → DOCX; - conflitti; - preservazione delle parti; - commenti o revisioni. Evidenze: - `tests/smoke/office-node.smoke.mjs`; - `skills/mcp-office-expert/evals/evals.json`. ### 3.4 Routing Il catalogo di routing viene generato a partire dagli `SKILL.md`, ma l’hook include anche keyword e hint curati manualmente. `mcp-office-expert` dispone attualmente di keyword generiche (`word`, `docx`, `office`) e di un hint che raccomanda la skill per Word, Excel e PDF. Le capability semantiche correnti sono: ```text document-conversion office-editing pdf-extraction report-generation ``` Mancano capability esplicite per: ```text docx-structural-editing markdown-docx-sync ooxml-manipulation word-comments word-revisions ``` Evidenze: - `scripts/build-routing-catalog.mjs`; - `scripts/hooks/sophia-user-prompt-submit.mjs`, blocchi `DOMAIN_KEYWORDS` e `SKILL_HINTS`; - `scripts/hooks/routing-semantic-overrides.json`. --- ## 4. Riferimento tecnico Anthropic ### 4.1 Fonte Riferimento consultato: - repository: `anthropics/skills`; - file: `skills/docx/SKILL.md`; - branch: `main`; - blob SHA rilevato: `fb954a460a1ea2294e9595e87fecce8df043eeba`; - URL: `https://github.com/anthropics/skills/blob/main/skills/docx/SKILL.md`; - data di consultazione: 30 luglio 2026. Licenza consultata: - file: `skills/docx/LICENSE.txt`; - blob SHA rilevato: `c55ab42224874608473643de0a85736b7fec0730`; - URL: `https://github.com/anthropics/skills/blob/main/skills/docx/LICENSE.txt`. ### 4.2 Pattern tecnici riusabili come riferimento Il riferimento Anthropic evidenzia: 1. per creare un nuovo DOCX è adatto `docx`/docx-js; 2. per modificare un DOCX esistente è preferibile operare sul package OOXML; 3. il testo visualmente contiguo può essere suddiviso in più run; 4. la manipolazione deve evitare riformattazione o pretty-print non necessari; 5. il package deve essere validato dopo la ricostruzione; 6. commenti e revisioni coinvolgono più parti XML e relationship; 7. le tracked changes richiedono semantica specifica per inserimenti, eliminazioni e paragraph mark; 8. la verifica visuale tramite rendering è una validazione complementare utile; 9. i file DOCX esterni devono essere trattati come input non affidabili. ### 4.3 Vincolo di licenza La skill DOCX Anthropic è dichiarata proprietaria e il relativo `LICENSE.txt` vieta, tra le altre cose, riproduzione, copia e creazione di opere derivate al di fuori dei diritti concessi dagli accordi Anthropic. Conseguenze implementative: - non copiare script, prompt o asset Anthropic; - non trasporre codice riga per riga; - non includere materiali Anthropic nel repository; - usare il documento soltanto come riferimento di requisiti e rischi tecnici; - implementare clean-room usando ECMA-376/ISO/IEC 29500, documentazione Microsoft pubblica, librerie con licenza compatibile e fixture proprie; - mantenere un file `THIRD_PARTY_NOTICES.md` per le dipendenze bundled nella skill. --- ## 5. Architettura proposta ## 5.1 Principio di separazione runtime La soluzione deve rispettare il seguente confine: ```text skill → chiamata MCP → office-node ``` oppure: ```text skill → script incluso nel bundle della skill ``` Non è ammesso: ```text skill → import diretto di file interni a office-node ``` Analogamente, `office-node` non deve richiedere che la skill sia installata per funzionare. ### 5.2 Architettura ibrida ```mermaid flowchart LR U["Richiesta utente"] --> S["mcp-office-expert"] S --> D{"Capability MCP disponibile?"} D -->|Sì| M["office-node / word_document"] D -->|No o diagnostica avanzata| B["tool OOXML bundled nella skill"] M --> V["Validazione DOCX"] B --> V V --> O["Nuovo DOCX + piano/changelog/warning"] ``` ### 5.3 Percorso MCP prioritario Il percorso normale deve essere `word_document`, esteso senza rimuovere le action legacy. Contratto proposto: ```text action = inspect | section | sync | validate intent = valore specifico del dominio ``` Matrice iniziale: | Action | Intent | | --- | --- | | `inspect` | `outline`, `package`, `sync_status` | | `section` | `read`, `replace_content`, `append`, `prepend`, `insert_after`, `delete`, `rename` | | `sync` | `link_source`, `plan_from_markdown`, `apply_from_markdown` | | `validate` | `package`, `preservation`, `sync_manifest` | Il raggruppamento `action` + `intent` evita di espandere indefinitamente l’enum delle action e mantiene il pattern consolidato nel repository. La validazione dei parametri deve essere eseguita server-side per ogni coppia action/intent. ### 5.4 Percorso OOXML bundled Gli strumenti diretti devono risiedere nella skill installata. Per coerenza con la struttura attuale di `mcp-office-expert`, è preferibile estendere `tools/` anziché introdurre una seconda convenzione locale. Struttura proposta: ```text skills/mcp-office-expert/ ├── SKILL.md ├── references/ │ ├── docx-structural-editing.md │ ├── markdown-docx-sync.md │ ├── docx-ooxml-package.md │ └── docx-validation-security.md ├── tools/ │ ├── catalog.json │ └── docx/ │ ├── README.md │ ├── src/ │ │ ├── cli.mjs │ │ ├── package-reader.mjs │ │ ├── package-writer.mjs │ │ ├── outline.mjs │ │ ├── section-range.mjs │ │ ├── section-edit.mjs │ │ ├── markdown-sync.mjs │ │ ├── relationships.mjs │ │ ├── content-types.mjs │ │ ├── comments.mjs │ │ ├── revisions.mjs │ │ ├── validation.mjs │ │ └── security.mjs │ ├── dist/ │ │ └── docx-ooxml-cli.mjs │ ├── package.json │ ├── package-lock.json │ └── THIRD_PARTY_NOTICES.md └── evals/ └── evals.json ``` Il file sotto `dist/` deve essere autocontenuto. A runtime non deve: - eseguire `npm install`; - cercare `office-node/node_modules`; - dipendere dal root del repository; - dipendere dal `cwd`; - importare file esterni alla skill; - scrivere nel repository di distribuzione. ### 5.5 Condivisione di codice solo a build time Per evitare divergenze tra MCP e skill, è raccomandato un core sorgente condiviso esclusivamente durante build e test: ```text packages/docx-ooxml-core/ ├── src/ ├── fixtures/ └── tests/ ``` Il build produce due artefatti indipendenti: ```text office-node/lib/generated/docx-ooxml-core.mjs skills/mcp-office-expert/tools/docx/dist/docx-ooxml-cli.mjs ``` Vincoli: - nessun import runtime incrociato; - gli artefatti generati devono essere committati o prodotti dall’installer/build previsto dal repository; - il bundle della skill deve funzionare dopo copia o symlink della sola skill; - il server MCP deve funzionare senza installazione della skill; - le dipendenze e le licenze devono essere tracciate. Questa estrazione può essere posticipata dopo il prototipo. Nella prima milestone è comunque obbligatoria la parità contrattuale tramite fixture e test condivisi, anche se il codice non è ancora centralizzato. --- ## 6. Modello documentale per capitoli e sezioni ### 6.1 Outline DOCX L’outline deve essere derivato prioritariamente da: 1. stili built-in `Heading 1`–`Heading 9`; 2. `w:outlineLvl`; 3. stili personalizzati collegati a livelli outline; 4. numerazione e gerarchia dei paragrafi; 5. fallback dichiarato basato sul testo del titolo. Output proposto: ```json { "ok": true, "action": "inspect", "intent": "outline", "sections": [ { "id": "sec-authentication", "title": "Autenticazione", "level": 2, "parent_id": "sec-architecture", "start_paragraph": 18, "end_paragraph": 31, "heading_bookmark": "sophia_sec_authentication", "match_confidence": "exact" } ], "warnings": [] } ``` ### 6.2 Definizione del range di sezione Per un heading di livello `N`, la sezione include: - il paragrafo heading; - i paragrafi successivi; - le sottosezioni di livello maggiore di `N`; - fino al successivo heading di livello minore o uguale a `N`. Per `replace_content` devono essere supportate due semantiche: ```json { "preserve_heading": true, "preserve_child_sections": true } ``` - `preserve_child_sections: true`: sostituisce soltanto il contenuto introduttivo prima della prima sottosezione; - `preserve_child_sections: false`: sostituisce l’intero subtree della sezione. ### 6.3 Selettore di sezione Il selettore deve supportare: ```json { "section": { "id": "sec-authentication" } } ``` oppure: ```json { "section": { "title": "Autenticazione", "level": 2, "parent_title": "Architettura", "occurrence": 1 } } ``` Regole: - preferire l’ID stabile quando disponibile; - tentare prima il match esatto; - normalizzare spazi e maiuscole solo in modalità esplicita; - non scegliere arbitrariamente fra titoli duplicati; - restituire `AMBIGUOUS_SECTION` con le alternative; - non applicare una modifica quando la confidenza è inferiore alla soglia configurata. --- ## 7. Sincronizzazione incrementale Markdown → DOCX ### 7.1 Workflow di prima classe nella skill Lo scenario deve essere esplicitato nel `SKILL.md` come workflow principale: > Quando un DOCX è stato generato da Markdown e il Markdown cambia, non rigenerare automaticamente l’intero documento. Pianificare e applicare una sincronizzazione incrementale delle sole sezioni modificate, preservando contenuti e formattazione non mappati. ### 7.2 Linking iniziale Dopo la prima generazione DOCX, il sistema deve poter collegare il Markdown al documento: ```json { "action": "sync", "intent": "link_source", "file_path": "documentazione.docx", "markdown_path": "documentazione.md", "output_path": "documentazione-linked.docx" } ``` `link_source` deve: 1. analizzare l’outline Markdown; 2. analizzare l’outline DOCX; 3. costruire il matching gerarchico; 4. segnalare ambiguità; 5. assegnare ID stabili; 6. inserire bookmark sugli heading collegati; 7. salvare un manifest di sincronizzazione; 8. calcolare gli hash base; 9. validare il package; 10. produrre un nuovo DOCX. ### 7.3 Manifest di sincronizzazione Formato logico proposto: ```json { "schema_version": 1, "source": { "path_hint": "documentazione.md", "document_hash": "sha256:..." }, "sections": [ { "id": "sec-authentication", "source_heading_path": ["Architettura", "Autenticazione"], "source_level": 2, "heading_bookmark": "sophia_sec_authentication", "base_source_hash": "sha256:...", "base_target_hash": "sha256:..." } ] } ``` Persistenza raccomandata: - parte custom XML embedded nel DOCX con namespace versionato, per esempio `urn:sophia:docx-sync:v1`; - bookmark Word sugli heading per la localizzazione stabile; - esportazione sidecar JSON opzionale per diagnostica, non come unica fonte; - content type e relationship aggiunti secondo OPC; - validazione della presenza e coerenza del manifest. Punto aperto da prototipare: comportamento di conservazione della parte custom XML dopo salvataggi con Microsoft Word e LibreOffice. ### 7.4 Piano di sincronizzazione ```json { "action": "sync", "intent": "plan_from_markdown", "file_path": "documentazione-linked.docx", "markdown_path": "documentazione.md" } ``` Output: ```json { "ok": true, "changes": [ { "section_id": "sec-authentication", "title": "Autenticazione", "change": "modified_source", "confidence": "exact" }, { "section_id": "sec-monitoring", "title": "Monitoraggio", "change": "added", "insert_after": "sec-deployment" } ], "conflicts": [], "requires_apply": true } ``` Stati minimi: ```text unchanged modified_source modified_target modified_both added deleted renamed moved unmapped_source unmapped_target ambiguous ``` ### 7.5 Rilevamento conflitti La sincronizzazione deve confrontare: ```text base Markdown base DOCX Markdown corrente DOCX corrente ``` Matrice: | Markdown corrente | DOCX corrente | Esito | | --- | --- | --- | | invariato | invariato | `unchanged` | | modificato | invariato | applicabile automaticamente | | invariato | modificato | preservare DOCX | | modificato | modificato | conflitto | | aggiunto | n/a | proposta di inserimento | | eliminato | modificato | conflitto | Strategie esplicite: ```text skip prefer_markdown prefer_docx manual_merge ``` Default: `manual_merge`/stop per `modified_both`. Errore strutturato: ```text SECTION_SYNC_CONFLICT ``` ### 7.6 Applicazione ```json { "action": "sync", "intent": "apply_from_markdown", "file_path": "documentazione-linked.docx", "markdown_path": "documentazione.md", "output_path": "documentazione-updated.docx", "section_ids": [ "sec-authentication", "sec-monitoring" ], "preserve_unmapped_content": true, "overwrite": false } ``` `plan` e `apply` devono essere separati. `apply` deve poter ricevere un piano precedentemente restituito oppure ricalcolarlo e verificare che la baseline non sia cambiata. --- ## 8. Rendering del frammento Markdown ### 8.1 Strategia raccomandata Per contenuti Markdown complessi, la soluzione più coerente con la pipeline esistente è: 1. isolare la sezione Markdown; 2. convertirla in un DOCX temporaneo con Pandoc; 3. usare il DOCX target come `reference_doc_path` quando appropriato; 4. estrarre dal DOCX temporaneo gli elementi `w:body` pertinenti; 5. importare nel target i paragrafi e le dipendenze necessarie; 6. aggiornare relationship, media, numbering e content types; 7. sostituire soltanto il range della sezione target; 8. validare il risultato. ### 8.2 MVP di contenuti supportati Supporto richiesto nella prima versione: - heading; - paragrafi; - grassetto, corsivo e inline code; - elenchi puntati e numerati; - blocchi di codice; - tabelle semplici; - hyperlink; - immagini locali semplici. Supporto differibile: - footnote/endnote; - equation; - diagrammi embedded; - campi Word complessi; - content control; - oggetti OLE; - SmartArt; - sezioni con layout multiplo; - note a margine; - riferimenti incrociati complessi. Ogni elemento non supportato deve produrre warning o blocco, non degradazione silenziosa. ### 8.3 Preservazione degli stili Il frammento deve: - riusare gli style ID del documento target; - mappare heading e paragrafi sugli stili esistenti; - non importare indiscriminatamente l’intero `styles.xml` temporaneo; - evitare collisioni di numbering ID; - rimappare relationship ID; - conservare le dimensioni delle immagini quando la sostituzione non richiede un ridimensionamento; - segnalare gli stili mancanti. --- ## 9. Manipolazione XML conservativa ### 9.1 Problema della serializzazione completa La serializzazione DOM completa di `word/document.xml` può introdurre differenze non correlate: - ordine o forma delle dichiarazioni namespace; - spaziatura; - prefissi; - ordine degli attributi; - formattazione XML. Per l’editing per sezione è preferibile una strategia di splice sul testo XML originale: 1. leggere il payload XML raw; 2. tokenizzare in modo namespace-aware; 3. registrare gli offset di ogni paragrafo; 4. derivare outline e range; 5. sostituire soltanto l’intervallo raw interessato; 6. lasciare intatti i byte esterni al range; 7. ricostruire esclusivamente le parti modificate. ### 9.2 Criterio di preservazione Non è realistico richiedere che l’intero ZIP finale sia byte-identico, perché la ricostruzione può cambiare metadata o compressione. Il criterio verificabile deve essere: - payload delle parti non modificate con stesso SHA-256; - stessa lista delle parti salvo aggiunte intenzionali; - stessi relationship non coinvolti; - stessi media non coinvolti; - modifiche a `document.xml` confinate al range previsto; - modifiche a `[Content_Types].xml` e `.rels` soltanto quando necessarie. ### 9.3 Find/replace cross-run Il testo visibile può essere distribuito tra più `w:r`. La ricerca deve usare un indice logico: ```text testo visibile continuo ↕ mappa offset nodi w:t / w:delText / tab / break ``` Il replace deve: - preservare i run quando possibile; - rifiutare match che attraversano strutture incompatibili; - non eliminare marker di commento, bookmark o revisioni; - segnalare match multipli; - supportare scope per sezione; - avere modalità `dry_run`. --- ## 10. Contratto MCP proposto ### 10.1 Parametri comuni ```json { "action": "section", "intent": "replace_content", "file_path": "input.docx", "output_path": "output.docx", "overwrite": false, "dry_run": false } ``` Parametri aggiuntivi: ```text section section_id section_title section_level parent_title occurrence content_markdown markdown_path section_ids preserve_heading preserve_child_sections preserve_unmapped_content conflict_strategy expected_input_hash expected_manifest_version ``` ### 10.2 Regole di sicurezza contrattuale - `output_path` obbligatorio per tutte le modifiche nuove; - `overwrite: false` di default; - `file_path` e `output_path` non devono coincidere salvo opt-in esplicito futuro; - URL remoti non ammessi; - `.doc` read-only; - `.docm` bloccato o gestito solo in modalità preservazione dichiarata; - nessuna esecuzione di macro; - nessun fetch di external relationship; - `dry_run` obbligatoriamente senza scritture; - hash opzionale per prevenire race e modifiche concorrenti. ### 10.3 Output strutturato ```json { "ok": true, "tool": "word_document", "action": "sync", "intent": "apply_from_markdown", "input_path": "...", "output_path": "...", "save_path": "...", "resource_link": "artifact://office/...", "changed_sections": [], "preserved_parts": [], "changed_parts": [], "warnings": [], "validation": { "package_valid": true, "relationships_valid": true, "manifest_valid": true, "preservation_valid": true } } ``` ### 10.4 Errori strutturati ```text INPUT_NOT_FOUND OUTPUT_EXISTS INVALID_DOCX_EXTENSION INVALID_DOCX_PACKAGE ENCRYPTED_DOCUMENT_UNSUPPORTED MACRO_ENABLED_DOCUMENT_UNSUPPORTED ZIP_PATH_TRAVERSAL ZIP_BOMB_LIMIT_EXCEEDED XML_PARSE_ERROR OUTLINE_NOT_FOUND SECTION_NOT_FOUND AMBIGUOUS_SECTION UNSUPPORTED_SECTION_CONTENT MARKDOWN_SOURCE_NOT_FOUND SYNC_MANIFEST_NOT_FOUND SYNC_MANIFEST_INVALID SECTION_SYNC_CONFLICT RELATIONSHIP_BROKEN CONTENT_TYPE_MISSING VALIDATION_FAILED PANDOC_NOT_AVAILABLE ``` --- ## 11. Strumenti bundled nella skill ### 11.1 CLI unificata Esempi: ```bash node tools/docx/dist/docx-ooxml-cli.mjs inspect input.docx --json ``` ```bash node tools/docx/dist/docx-ooxml-cli.mjs outline input.docx --json ``` ```bash node tools/docx/dist/docx-ooxml-cli.mjs unpack input.docx --output workdir ``` ```bash node tools/docx/dist/docx-ooxml-cli.mjs validate workdir ``` ```bash node tools/docx/dist/docx-ooxml-cli.mjs pack workdir --output result.docx ``` ```bash node tools/docx/dist/docx-ooxml-cli.mjs sync-plan \ --markdown documentazione.md \ --docx documentazione.docx \ --json ``` ```bash node tools/docx/dist/docx-ooxml-cli.mjs sync-apply \ --markdown documentazione.md \ --docx documentazione.docx \ --output documentazione-updated.docx ``` ### 11.2 Quando la skill deve preferire MCP Usare MCP quando: - `office-mcp-server` è disponibile; - l’operazione è coperta da `word_document`; - il documento è collegato al Markdown; - la richiesta riguarda editing per sezione; - l’operazione può essere eseguita con output strutturato e validazione server-side; - serve registrazione dell’artifact. ### 11.3 Quando usare gli strumenti bundled Usare gli strumenti della skill quando: - MCP non è disponibile; - l’action o intent necessario non è esposto; - occorre diagnosticare direttamente il package; - il mapping è danneggiato; - bisogna ispezionare relationship o content types; - il documento usa stili heading non riconosciuti; - occorre preparare o verificare una nuova capability MCP; - il server restituisce un errore recuperabile che indica fallback OOXML; - l’utente richiede esplicitamente ispezione o patch OOXML. ### 11.4 Workflow diretto obbligatorio Per modifiche OOXML dirette: 1. ispezionare il package; 2. creare un output separato; 3. estrarre in directory temporanea; 4. bloccare symlink e path traversal; 5. identificare parti e relationship coinvolte; 6. applicare modifiche minime; 7. validare XML, OPC, relationship e content types; 8. ricostruire il DOCX; 9. riaprire e rieseguire l’ispezione; 10. confrontare gli hash delle parti non coinvolte; 11. eseguire verifica MCP o visuale quando disponibile; 12. restituire changelog e warning. --- ## 12. Aggiornamento di `mcp-office-expert` ### 12.1 Frontmatter La descrizione deve includere esplicitamente: - editing di DOCX esistenti; - modifica di capitoli/sezioni; - sincronizzazione incrementale da Markdown; - preservazione della formattazione; - commenti e tracked changes nelle milestone successive; - fallback OOXML con tool bundled. ### 12.2 Nuovi riferimenti Proposta: ```text references/docx-structural-editing.md references/markdown-docx-sync.md references/docx-ooxml-package.md references/docx-validation-security.md ``` Il `SKILL.md` deve rimanere control plane e caricare i riferimenti solo quando necessari. ### 12.3 Decision table MCP/script | Caso | Scelta primaria | | --- | --- | | Creazione iniziale Markdown → DOCX | `document_convert` | | Lettura/CRUD semplice legacy | `word_document` legacy | | Outline e modifica per capitolo | `word_document` section-aware | | Sincronizzazione Markdown → DOCX | `word_document` sync | | Diagnostica package | tool bundled | | Riparazione relationship/content types | tool bundled | | Intent MCP mancante | tool bundled | | MCP non disponibile | tool bundled | | Documento ambiguo o conflitto | piano senza apply | | Indicizzazione del risultato | `mcp-docs-navigator` | | Analisi cross-source | `mcp-technical-analyst` primario | | Asset SVG da inserire | `svg` → `mcp-office-expert` | ### 12.4 Catalogo helper Aggiornare `skills/mcp-office-expert/tools/catalog.json` con: ```text docx-ooxml-inspect docx-ooxml-validate docx-section-edit docx-markdown-sync ``` Ogni entry deve dichiarare: - script; - use case; - keyword; - esempio; - output primari; - preferenza MCP; - prerequisiti. --- ## 13. Routing, hook e sinergie ### 13.1 Keyword curate Aggiungere a `DOMAIN_KEYWORDS['mcp-office-expert']`: ```text modifica capitolo docx modifica sezione word sincronizza markdown docx aggiorna docx dal markdown preserva formattazione ooxml document.xml document.xml.rels tracked changes revisioni word commenti word redline header docx footer docx ``` ### 13.2 Hint Hint proposto: ```text Considera mcp-office-expert per creazione e modifica di documenti Word, incluso editing per capitolo e sincronizzazione incrementale Markdown→DOCX. Preferisci office-mcp-server per le operazioni supportate; usa i tool OOXML bundled per diagnostica, capability mancanti e fallback controllato. ``` ### 13.3 Semantic override Aggiungere capability: ```text docx-structural-editing markdown-docx-sync ooxml-manipulation word-comments word-revisions ``` Compatibilità consigliate: ```text mcp-docs-navigator mcp-database-expert mcp-technical-analyst svg ``` ### 13.4 Discovery automatica L’aggiornamento del `SKILL.md` alimenta automaticamente il catalogo generato da `scripts/build-routing-catalog.mjs`. Restano manuali: - keyword ad alto peso; - hint curato; - override semantico; - eval e smoke dell’hook. --- ## 14. Evals dedicati ### 14.1 Estensione di `eval_focus` Proposta: ```json [ "word-edit-flow-controllato", "docx-section-aware-editing", "markdown-docx-incremental-sync", "mcp-versus-bundled-tool-selection", "docx-preservation-and-conflicts", "excel-report-flow", "pdf-export-text-plus-handoff-docs" ] ``` ### 14.2 Eval — aggiornamento singola sezione Prompt: ```text Il file architecture.md è stato aggiornato. Riporta nel DOCX soltanto le modifiche al capitolo “Autenticazione” e preserva il resto. ``` Atteso: - seleziona `mcp-office-expert`; - non rigenera il DOCX completo; - esegue `plan_from_markdown`; - applica soltanto la sezione; - salva su nuovo output; - valida preservazione e package. ### 14.3 Eval — modifica diretta di capitolo Prompt: ```text Nel DOCX aggiungi alla fine del capitolo “Limitazioni” una nota sul supporto offline. Non cambiare le sottosezioni. ``` Atteso: - ispeziona l’outline; - risolve la sezione; - usa `section/append`; - mantiene le sottosezioni; - non usa indice di paragrafo. ### 14.4 Eval — titolo ambiguo Prompt: ```text Aggiorna la sezione “Configurazione”. ``` Fixture con due sezioni omonime. Atteso: - restituisce `AMBIGUOUS_SECTION`; - usa parent e level per disambiguare; - non modifica alcun file prima della risoluzione. ### 14.5 Eval — conflitto Prompt: ```text Sincronizza il capitolo Deployment: è stato modificato sia nel Markdown sia nel DOCX. ``` Atteso: - rileva `modified_both`; - non sovrascrive; - restituisce conflitto; - non assume `prefer_markdown`. ### 14.6 Eval — DOCX legacy senza manifest Prompt: ```text Questo DOCX deriva dal Markdown ma non contiene informazioni di collegamento. Aggiornalo con le ultime modifiche. ``` Atteso: - confronta gli outline; - produce un piano con confidence; - usa tool bundled se necessario; - non applica match ambigui; - propone `link_source`. ### 14.7 Eval — scelta MCP/script Prompt: ```text Modifica il capitolo Architettura; office-mcp-server espone section/replace_content. ``` Atteso: MCP, non script. Prompt: ```text Ripara document.xml.rels e verifica i content types. ``` Atteso: tool bundled, output separato, validazione. ### 14.8 Eval — preservazione Prompt: ```text Aggiorna il DOCX dal Markdown. Il Word contiene copertina, commenti, header/footer e un’appendice aggiunta manualmente. ``` Atteso: - `preserve_unmapped_content: true`; - nessuna rigenerazione completa; - hash invariati per le parti non coinvolte; - warning se una parte non è verificabile. ### 14.9 Eval — composizione Prompt: ```text Genera il report tecnico in DOCX dal Markdown, poi aggiorna il capitolo KPI dopo la revisione dei dati e indicizza il risultato. ``` Atteso: 1. `mcp-database-expert` se occorre calcolare i KPI; 2. `mcp-office-expert` per generazione e sync; 3. `mcp-docs-navigator` per indicizzazione. --- ## 15. Test e fixture ### 15.1 Fixture minime Proposta: ```text tests/fixtures/docx/ ├── simple-headings.docx ├── nested-headings.docx ├── duplicate-headings.docx ├── custom-heading-style.docx ├── split-runs.docx ├── formatted-runs.docx ├── hyperlinks-bookmarks.docx ├── comments.docx ├── tracked-changes.docx ├── headers-footers.docx ├── images.docx ├── tables-lists-code.docx ├── linked-markdown.docx ├── manually-diverged.docx ├── broken-relationship.docx ├── invalid-content-type.docx ├── encrypted.docx ├── macro-enabled.docm ├── zip-slip.docx └── zip-bomb-threshold.docx ``` Markdown corrispondenti: ```text tests/fixtures/docx/markdown/ ├── initial.md ├── changed-one-section.md ├── added-section.md ├── renamed-section.md ├── deleted-section.md └── conflicting-section.md ``` ### 15.2 Nuove suite proposte ```text tests/smoke/office-node-docx-editing.smoke.mjs tests/smoke/office-node-docx-sync.smoke.mjs tests/smoke/office-skill-docx-tools.smoke.mjs tests/smoke/office-docx-parity.smoke.mjs ``` Aggiornare: ```text scripts/test-suite-registry.mjs tests/smoke/run-all.test.mjs ``` solo secondo il pattern corrente del repository. ### 15.3 Casi di test obbligatori - outline nested; - heading personalizzato; - titolo duplicato; - replace con e senza sottosezioni; - append e prepend; - inserimento di nuova sezione; - rinomina; - eliminazione; - match cross-run; - preservazione di bold/italic; - hyperlink e bookmark; - comment anchors; - revision markup; - immagini e relationship; - numbering ID; - media non coinvolti invariati; - manifest valido e corrotto; - conflitto a tre vie; - file output già esistente; - input e output coincidenti; - path traversal; - limite decompressione; - documento encrypted; - `.docm`; - tool bundled eseguito dalla directory installata della skill; - esecuzione con `cwd` esterno; - assenza di `office-node`; - assenza di Pandoc; - parità di piano e error code tra MCP e CLI; - schema MCP con `items` su ogni array; - response `structuredContent`. ### 15.4 Verifica Word e LibreOffice Quando disponibili: - apertura e salvataggio con Microsoft Word; - conversione headless con LibreOffice; - rendering PDF; - confronto visivo di pagine interessate e non interessate. La verifica visuale non sostituisce la validazione strutturale. --- ## 16. Sicurezza ### 16.1 Input DOCX non affidabile Proteggere da: - ZIP path traversal; - symlink; - decompression bomb; - numero e dimensione eccessiva delle entry; - XML entity expansion; - external relationship; - file encrypted; - macro; - path remoti; - overwrite accidentale; - output fuori scope quando il runtime impone root consentite. ### 16.2 Limiti suggeriti I valori devono essere configurabili e testati. Il prototipo deve definire: - dimensione massima compressa; - dimensione massima decompressa; - rapporto massimo di compressione; - numero massimo di entry; - dimensione massima di una parte XML; - timeout per Pandoc e validazione; - dimensione massima del manifest; - numero massimo di sezioni e match. Non fissare valori definitivi senza fixture e misurazioni. ### 16.3 Macro Per `.docm`: - non eseguire macro; - non convertire silenziosamente in `.docx`; - bloccare nel primo rilascio oppure preservare la parte macro solo dopo test specifici; - restituire warning esplicito. --- ## 17. Piano implementativo per milestone ## Architettura del piano ```mermaid flowchart LR M1["M1 - Fondazione OOXML"] --> M2["M2 - Editing per sezione"] M2 --> M3["M3 - Sync Markdown→DOCX"] M3 --> M4["M4 - Commenti, revisioni, immagini"] M1 --> M5["M5 - Routing, eval e hardening"] M2 --> M5 M3 --> M5 M4 --> M5 ``` ## Milestone 1 — Fondazione OOXML e bundle della skill ### Obiettivo Creare il layer sicuro e verificabile per leggere, estrarre, ricostruire e validare package DOCX. ### Attività - introdurre package reader/writer; - mantenere raw bytes delle parti non modificate; - introdurre protezioni ZIP; - implementare inspect, unpack, pack e validate; - creare CLI bundled autocontenuta; - aggiornare `tools/catalog.json`; - aggiungere fixture e smoke; - documentare dipendenze e licenze; - definire error code comuni. ### Deliverable - CLI skill funzionante senza `office-node`; - libreria MCP-side equivalente; - report di validazione; - fixture di sicurezza; - test di parità base. ### Criteri di completamento - unpack/pack round-trip valido; - nessun path traversal; - output separato; - parti non modificate con hash invariato; - bundle eseguibile dalla skill installata. ### Rischi - serializzazione XML rumorosa; - bundle troppo grande; - comportamento ZIP differente tra piattaforme. ## Milestone 2 — Editing semantico per sezione ### Obiettivo Abilitare “modifica il capitolo X del DOCX”. ### Attività - outline Word; - selettore di sezione; - range gerarchici; - read/replace/append/prepend/insert/delete/rename; - rendering Markdown fragment; - action MCP `inspect`, `section`, `validate`; - output strutturato; - preservazione e changelog. ### Deliverable - editing per capitolo via MCP; - fallback CLI; - smoke su heading standard e personalizzati; - eval su richieste naturali. ### Criteri di completamento - nessun uso obbligatorio degli indici di paragrafo; - titolo ambiguo bloccato; - parti esterne preservate; - output riapribile; - stili base coerenti. ### Rischi - stili personalizzati; - tabelle e liste complesse; - collisioni numbering/relationship. ## Milestone 3 — Sincronizzazione incrementale Markdown → DOCX ### Obiettivo Aggiornare solo le sezioni Markdown cambiate nel DOCX già rifinito. ### Attività - `link_source`; - manifest embedded; - bookmark stabili; - hash per sezione; - `plan_from_markdown`; - `apply_from_markdown`; - rilevamento conflitti a tre vie; - preservazione contenuti non mappati; - integrazione opzionale nella pipeline di pubblicazione. ### Deliverable - DOCX linked; - piano di sync; - apply selettivo; - conflitti strutturati; - fixture initial/changed/conflicting. ### Criteri di completamento - una modifica Markdown locale produce una modifica DOCX locale; - nessuna rigenerazione completa; - conflitto non sovrascritto; - appendice manuale preservata; - manifest aggiornato dopo apply. ### Rischi - perdita del manifest dopo salvataggio esterno; - rename/move di heading; - modifiche editoriali interne alla stessa sezione. ## Milestone 4 — Capability avanzate ispirate al riferimento Anthropic ### Obiettivo Coprire progressivamente le operazioni DOCX professionali più rilevanti. ### Attività - find/replace cross-run; - sostituzione immagini; - commenti e reply; - tracked insert/delete/replace; - accept/reject changes; - validazione autore revisioni; - edge case paragraph mark; - verifica Word/LibreOffice. ### Deliverable - action/intent MCP dedicati; - comandi CLI equivalenti; - fixture commenti/revisioni; - test di parità. ### Criteri di completamento - commenti visibili e correttamente ancorati; - revisioni valide; - nessuna modifica non tracciata quando richiesto; - immagini e relationship coerenti. ### Rischi - elevata complessità schema OOXML; - differenze Word/LibreOffice; - comportamento di accept/reject su paragrafi eliminati. ## Milestone 5 — Skill, routing, eval e hardening ### Obiettivo Rendere la capability correttamente discoverable e guidare l’agente nella scelta MCP/script. ### Attività - aggiornare `SKILL.md`; - aggiungere riferimenti progressivi; - aggiornare catalogo helper; - aggiornare keyword e hint hook; - aggiornare semantic override; - ampliare eval; - aggiungere smoke routing; - aggiornare documentazione locale; - eseguire gate `test:affected -- --strict` con le suite pertinenti. ### Deliverable - skill aggiornata; - routing verificato; - eval dedicati; - documentazione MCP e helper; - handoff di riavvio server. ### Criteri di completamento - prompt “modifica capitolo” instradato a Office Expert; - MCP preferito quando disponibile; - fallback OOXML usato solo nei casi previsti; - nessuna competizione con una seconda skill DOCX; - suite affected conclusa. --- ## 18. Criteri di accettazione complessivi ### Funzionali 1. È possibile leggere l’outline di un DOCX. 2. È possibile leggere e modificare una sezione tramite titolo gerarchico o ID. 3. È possibile aggiornare un solo capitolo dal Markdown. 4. È possibile pianificare la sincronizzazione senza scrivere. 5. È possibile rilevare sezioni aggiunte, modificate, eliminate e in conflitto. 6. Un conflitto non viene sovrascritto per default. 7. Il documento originale non viene modificato per default. 8. Il nuovo DOCX è riapribile e strutturalmente valido. 9. Gli strumenti bundled funzionano senza dipendere da `office-node`. 10. Le action MCP funzionano senza dipendere dall’installazione della skill. ### Preservazione 11. Le parti non coinvolte mantengono lo stesso payload/hash. 12. Header, footer, copertina e appendici non mappate restano inalterati. 13. Commenti e revisioni esterni alla sezione target restano inalterati. 14. Media e relationship non coinvolti restano inalterati. 15. Le modifiche intenzionali sono elencate nel changelog. ### Sicurezza 16. ZIP slip e symlink sono bloccati. 17. I limiti di decompressione sono applicati. 18. Macro ed encrypted DOCX sono gestiti con stop/warning esplicito. 19. Nessuna risorsa esterna viene caricata automaticamente. 20. `dry_run` non produce scritture. ### Skill e routing 21. `mcp-office-expert` è la skill primaria per editing DOCX. 22. `mcp-technical-analyst` resta primario per analisi multi-sorgente. 23. `mcp-docs-navigator` interviene dopo la produzione quando serve indicizzazione. 24. `svg` prepara asset vettoriali prima della sostituzione nel DOCX. 25. Gli eval distinguono correttamente MCP e tool bundled. --- ## 19. Validazioni consigliate ### Gate repository Applicare le regole correnti del repository: - modifiche incrementali; - compatibilità legacy; - schema check; - smoke test; - documentazione aggiornata; - un solo gate locale conclusivo: ```bash npm run test:affected -- --strict --include ``` Le suite esatte devono essere ricavate dal registry dopo l’implementazione; non usare `npm test`, `test:all` o `test:ci` localmente se vietato dalle regole repository. ### Validazione contrattuale - tool schema compatibile con client MCP severi; - ogni array dichiara `items`; - action e intent validati; - error code stabili; - output `structuredContent`; - `resource_link` per gli artifact prodotti; - backward compatibility delle action legacy. ### Validazione documentale - DOCX aperto da Word; - DOCX aperto da LibreOffice; - rendering PDF quando disponibile; - outline prima/dopo; - hash delle parti; - diff XML confinato; - test di commenti e revisioni; - test multi-piattaforma. --- ## 20. Rischi e punti aperti ### RSK-01 — Manifest embedded Non è ancora verificato che la parte custom XML proposta venga sempre preservata dopo salvataggi Word e LibreOffice. Validazione richiesta: - creare prototipo; - aprire/salvare con entrambi; - verificare manifest, relationship e bookmark. ### RSK-02 — Trapianto di frammenti Pandoc Il trapianto di una sezione DOCX temporanea può richiedere merge di: - numbering; - styles; - media; - relationships; - footnote; - hyperlink. Mitigazione: - MVP con subset dichiarato; - blocco per costrutti non supportati; - fixture dedicate. ### RSK-03 — Modifiche concorrenti Il confronto per hash può rilevare che entrambe le copie sono cambiate, ma non risolve automaticamente il significato del conflitto. Mitigazione: - piano separato; - stop di default; - strategia esplicita; - manual merge. ### RSK-04 — Rumore XML Una serializzazione completa può alterare l’intero `document.xml`. Mitigazione: - scanner con offset; - splice raw; - hash e diff di preservazione. ### RSK-05 — Parità MCP/CLI Due implementazioni indipendenti possono divergere. Mitigazione: - contratto comune; - fixture condivise; - test di parità; - core condiviso solo a build time quando stabilizzato. ### RSK-06 — Licenza Anthropic Il riferimento è proprietario. Mitigazione: - clean-room; - nessun codice o prompt copiato; - fonti pubbliche OOXML; - revisione licenze delle dipendenze; - notices. ### RSK-07 — Ampiezza dello scope Commenti e revisioni possono rallentare la feature principale. Mitigazione: - priorità a section editing e sync; - capability avanzate in milestone separata. --- ## 21. Handoff implementativo Ordine raccomandato: 1. prototipare package reader/writer e preservazione; 2. implementare outline e range di sezione; 3. aggiungere `inspect` e `section` a `word_document`; 4. distribuire CLI skill con inspect/validate/section; 5. aggiungere fixture ed eval minimi; 6. prototipare manifest e `link_source`; 7. implementare plan/apply e conflitti; 8. integrare la pipeline Markdown → DOCX; 9. estendere a commenti, revisioni e immagini; 10. aggiornare routing, semantic override e documentazione; 11. eseguire il gate affected; 12. documentare che le modifiche al server richiedono il riavvio di `office-mcp-server`. La prima release utile deve chiudere il seguente scenario end-to-end: ```text Dato un DOCX inizialmente generato da Markdown e successivamente rifinito, individuare il capitolo modificato nel Markdown, produrre un piano, aggiornare solo quel capitolo in un nuovo DOCX, preservare il resto del documento e validare il risultato. ``` --- ## 22. Indice delle fonti ### Repository target - `[R1]` `skills/mcp-office-expert/SKILL.md` Baseline `407677463f1944ffc4d6c1051c0975bb0c4b12be`. - `[R2]` `skills/mcp-office-expert/tools/catalog.json` Baseline `407677463f1944ffc4d6c1051c0975bb0c4b12be`. - `[R3]` `skills/mcp-office-expert/evals/evals.json` Baseline `407677463f1944ffc4d6c1051c0975bb0c4b12be`. - `[R4]` `office-node/index.js` Baseline `407677463f1944ffc4d6c1051c0975bb0c4b12be`. - `[R5]` `office-node/package.json` Baseline `407677463f1944ffc4d6c1051c0975bb0c4b12be`. - `[R6]` `tests/smoke/office-node.smoke.mjs` Baseline `407677463f1944ffc4d6c1051c0975bb0c4b12be`. - `[R7]` `scripts/build-routing-catalog.mjs` Baseline `407677463f1944ffc4d6c1051c0975bb0c4b12be`. - `[R8]` `scripts/hooks/sophia-user-prompt-submit.mjs` Baseline `407677463f1944ffc4d6c1051c0975bb0c4b12be`. - `[R9]` `scripts/hooks/routing-semantic-overrides.json` Baseline `407677463f1944ffc4d6c1051c0975bb0c4b12be`. - `[R10]` `AGENTS.md` Regole su pattern `action`, compatibilità schema, test affected e bundle skill. ### Fonte esterna ufficiale - `[A1]` Anthropic, `skills/docx/SKILL.md`, branch `main`, blob `fb954a460a1ea2294e9595e87fecce8df043eeba`. URL: https://github.com/anthropics/skills/blob/main/skills/docx/SKILL.md Consultato il 30 luglio 2026. Limite: riferimento tecnico source-available; non prova il comportamento runtime di Claude e non costituisce codice riutilizzabile. - `[A2]` Anthropic, `skills/docx/LICENSE.txt`, branch `main`, blob `c55ab42224874608473643de0a85736b7fec0730`. URL: https://github.com/anthropics/skills/blob/main/skills/docx/LICENSE.txt Consultato il 30 luglio 2026. Limite: la valutazione legale definitiva delle condizioni applicabili compete ai responsabili del progetto; tecnicamente si raccomanda implementazione clean-room. ### Fonte funzionale - `[F1]` Decisioni e scenario forniti dall’utente nella conversazione: repository come contenitore di MCP e skill separatamente distribuibili; preferenza per architettura ibrida; script OOXML bundled; MCP prioritario; eval dedicati; scenario principale di aggiornamento incrementale di un DOCX generato inizialmente da Markdown.