# Micro-milestone: Codex hooks portabili per routing MCP/Skill e contesto Docs/Memory

Versione: 2026-05-13  
Stato: proposta operativa pronta per implementazione  
Ambito: `sophiadeveloper/mcp-servers`

## 1. Obiettivo

Questa micro-milestone introduce un primo livello di hooks Codex portabili per migliorare il comportamento degli agenti senza anticipare tutta la Milestone 8.

L'obiettivo e' generare un `hooks.json` pronto da installare manualmente in `~/.codex/hooks.json`, con comandi che puntano a script versionati nel repository `mcp-servers`, evitando di copiare gli script hook nel profilo utente.

In questa micro-milestone l'applicazione nel profilo utente resta esplicitamente manuale: lo script non deve modificare `~/.codex/hooks.json`, non deve fare merge automatico e non deve creare backup nel profilo utente.

Gli hooks devono:

- caricare un bootstrap leggero a inizio sessione;
- ricordare all'agente quando valutare l'uso di Docs MCP e Memory MCP;
- suggerire MCP o skill coerenti con il prompt utente;
- fornire reminder critici per MCP specifici, ad esempio SQL read-only o ColdFusion evaluate;
- restare non bloccanti nella prima iterazione;
- non sostituire `AGENTS.md`, `SKILL.md`, regole condivise o configurazioni MCP;
- non duplicare contenuto lungo gia' presente nei file di regole.

## 2. Principio architetturale

La configurazione utente, quando l'utente applica manualmente il risultato, deve contenere solo il file runtime host-specifico:

```text
~/.codex/hooks.json
```

Gli script hook restano nel repository:

```text
scripts/hooks/sophia-session-start.mjs
scripts/hooks/sophia-user-prompt-submit.mjs
scripts/hooks/sophia-pretool-sql.mjs
scripts/hooks/sophia-pretool-coldfusion.mjs
scripts/hooks/sophia-pretool-memory.mjs
```

Il `hooks.json` generato contiene comandi `node` con path assoluti verso il repository locale.

Esempio concettuale:

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear",
        "hooks": [
          {
            "type": "command",
            "command": "node \"D:\\\\mcp-servers\\\\scripts\\\\hooks\\\\sophia-session-start.mjs\" --repo-root \"D:\\\\mcp-servers\"",
            "timeout": 8,
            "statusMessage": "Loading Sophia bootstrap"
          }
        ]
      }
    ]
  }
}
```

Vantaggi:

- aggiornando il repository si aggiornano automaticamente gli hook script;
- il profilo utente resta leggero;
- si riduce il rischio di drift tra copie locali;
- si mantiene una fonte unica per logica di routing e reminder;
- l'installazione manuale resta ispezionabile prima di qualsiasi modifica al profilo utente.

## 3. Non obiettivi

Questa micro-milestone non deve:

- completare tutta la Milestone 8;
- installare o copiare skill in `$HOME/.agents/skills`;
- generare runtime Copilot / VS Code;
- dichiarare compatibilita' ufficiale con VS Code/Copilot hooks;
- sostituire o riscrivere `AGENTS.md`;
- eseguire chiamate MCP direttamente dagli hook;
- modificare automaticamente `~/.codex/hooks.json` o altri file del profilo utente;
- fare merge automatico con hook utente esistenti;
- patchare automaticamente `~/.codex/config.toml`;
- bloccare prompt o tool use salvo casi futuri esplicitamente progettati;
- introdurre registry YAML come fonte di verita' per le skill;
- duplicare contenuti estesi di `SKILL.md`, `GLOBAL.md` o documentazione condivisa.

## 4. File proposti

### 4.1 Script hook runtime

```text
scripts/hooks/sophia-session-start.mjs
scripts/hooks/sophia-user-prompt-submit.mjs
scripts/hooks/sophia-pretool-sql.mjs
scripts/hooks/sophia-pretool-coldfusion.mjs
```

Gli script devono essere autonomi, veloci e conservativi.

Regole comuni:

- usare Node.js, non Python;
- leggere input da stdin quando l'evento lo prevede;
- in assenza di match, uscire con codice 0 e senza output;
- non produrre stack trace o output rumoroso in condizioni normali;
- limitare `additionalContext` a contenuto breve e operativo;
- non assumere che il current working directory sia il repository;
- accettare `--repo-root <path>`;
- fallire in modo conservativo: meglio nessun output che bloccare il flusso.

### 4.2 Script generator

```text
scripts/generate-codex-hooks.js
```

`generate-codex-hooks.js` genera un `hooks.json` completo o un frammento hooks gestito dal repository, senza scrivere nel profilo utente.

La scrittura in `~/.codex/hooks.json` e l'eventuale merge con hook esistenti sono a cura dell'utente in questa fase. Il generatore deve quindi privilegiare output chiaro, ispezionabile e copiabile.

Comandi previsti:

```bash
node scripts/generate-codex-hooks.js --root D:\mcp-servers
node scripts/generate-codex-hooks.js --root D:\mcp-servers --force-output
node scripts/generate-codex-hooks.js --root D:\mcp-servers --output .\generated\codex-hooks.json
node scripts/generate-codex-hooks.js --root /home/davide/mcp-servers
node scripts/generate-codex-hooks.js --root . --check-config
```

Flag consigliati:

```text
--root <path>              root repo mcp-servers
--output <path>            file locale dove salvare il JSON generato; default: <root>/codex-hooks.generated.json
--force-output             sovrascrive il file output se esiste, incluso quello default
--fragment                 genera solo il blocco hooks gestito invece del file completo
--home <path>              home utente da usare solo per calcolare path e warning, utile nei test
--check-config             segnala se ~/.codex/config.toml sembra non abilitare gli hook, senza modificarlo
--json                     report machine-readable
-h, --help                 aiuto
```

Regole:

- nessuna scrittura in `~/.codex` o in altre directory utente di default;
- se `--output` e' omesso, scrivere in `codex-hooks.generated.json` nella root repo;
- `codex-hooks.generated.json` deve essere ignorato da git;
- se il file output esiste, non sovrascrivere senza `--force-output`;
- `--check-config` puo' leggere `~/.codex/config.toml` solo per produrre un warning;
- se trova `codex_hooks = false`, non deve modificarlo e deve indicare che l'abilitazione resta manuale o demandata a una fase M8 separata.

### 4.3 Documentazione

```text
docs/codex-user-hooks.md
```

Contenuti minimi:

- scopo degli hooks;
- differenza tra hook, skill, MCP server e file di regole;
- generazione del file hooks;
- installazione manuale in `~/.codex/hooks.json`;
- merge manuale con hook esistenti;
- nota su `codex_hooks = true` in `~/.codex/config.toml`, senza patch automatica;
- rollback manuale;
- come disabilitare gli hook;
- come aggiungere nuovi MCP/skill al routing;
- troubleshooting Windows/Linux;
- regole di sicurezza: non bloccare, non duplicare regole lunghe, non trasformare hooks in agenti autonomi.

## 5. Eventi hook iniziali

### 5.1 SessionStart

Scopo: caricare nel contesto il contenuto di `AGENTS.md` effettivo a inizio sessione.

Trigger consigliato:

```text
startup|resume|clear
```

Output atteso:

```json
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Sophia bootstrap loaded from <path>/AGENTS.md:\n\n<AGENTS.md content>"
  }
}
```

Linee guida:

- leggere solo `AGENTS.md`: le ulteriori istruzioni devono essere referenziate da quel file;
- cercare `AGENTS.md` dal current working directory verso l'alto, poi usare `--repo-root` come fallback;
- non elencare decine di skill;
- non leggere contenuti pesanti;
- se `AGENTS.md` manca o non e' leggibile, emettere un warning breve non bloccante.

### 5.2 UserPromptSubmit

Scopo: guardare il prompt utente e suggerire routing o valutazioni contestuali.

Questo hook deve leggere lo stdin JSON, estrarre il prompt e produrre output solo quando esiste un match abbastanza forte.

Categorie iniziali:

| Categoria | Segnali prompt | Suggerimento |
| --- | --- | --- |
| Docs | documentazione, docs, manuale, procedura, specifica, policy, tag, knowledge | valutare `docs-mcp-server` / `mcp-docs-navigator` |
| Memory | ricordi, memory, decisione, handoff, workaround, root cause, storico, vincolo | valutare `memory-mcp-server` / `mcp-memory-operator` |
| Multi-source analysis | ticket, Mantis, commit, log, allegati, timeline, root cause, regressione | valutare `mcp-technical-analyst` |
| Multi-phase coordination | piano, milestone, coordina, orchestrazione, multi-fase, handoff | valutare `mcp-master-orchestrator` |
| Code review | review, diff, PR, pull request, regressione codice | valutare `mcp-code-reviewer` |
| SQL/data | SQL, query, schema, database, dati, report dati | valutare `mcp-database-expert` e SQL MCP read-only |
| ColdFusion/CFML | ColdFusion, CFML, cfcomponent, cfquery, application scope, evaluate | valutare `mcp-coldfusion-developer` e CF MCP |
| Projectfs/rules | GLOBAL.md, RULES.md, SUBAGENTS.md, symlink, fuori workspace, shared drive | valutare `projectfs-mcp-server` |
| Sophia/Yii | Sophia, Yii, RenderSettings, FrmGridView, controllerMap, Cruge, Gii | valutare `mcp-sophia-yii-developer` |
| Git/Mantis | Mantis, rebase, conflitti, branch, blame, range-diff, allegati | valutare `mcp-git-mantis-workflow` |
| Browser/UI | UI, DOM, screenshot, console, network, Playwright | valutare `mcp-browser-automation` |
| Office | Word, Excel, PDF, DOCX, XLSX, PPTX | valutare `mcp-office-expert` |
| Token discipline | log lunghi, dump, Base64, file grandi, payload grandi | applicare output/token discipline |
| Sub-agent | sub-agent, delegazione, parallelismo, explorer, implementer | leggere `SUBAGENTS.md` prima di delegare |

Esempio output docs:

```json
{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "This prompt may benefit from docs-mcp. Before answering from memory, consider docs search; if empty, inspect tags/list documents and retry with IT/EN domain synonyms before concluding no docs exist."
  }
}
```

Esempio output memory:

```json
{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "This prompt may benefit from memory-mcp. Search/read project-scoped memory for prior decisions, root causes, constraints or handoff notes, but verify against docs/code/tickets before acting."
  }
}
```

Esempio output combinato:

```json
{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "This prompt may benefit from both docs and memory. Use docs/code/tickets as primary evidence and memory as contextual recall; reconcile conflicts explicitly."
  }
}
```

Linee guida:

- massimo due suggerimenti per prompt;
- preferire precisione rispetto a recall aggressivo;
- se match debole, nessun output;
- non forzare l'uso di una skill;
- non inventare skill non installabili o non presenti nel repo;
- usare messaggi brevi e non vincolanti.
- per ColdFusion e Sophia/Yii, usare un router context-aware: segnali espliciti del prompt producono sempre hint; segnali generici producono hint solo se il repo attivo contiene marker coerenti.
- marker ColdFusion iniziali: `Application.cfc`, file `.cfm`, file `.cfc`.
- marker Sophia/Yii iniziali: `protected/yiic`, `protected/config/config_frm.php`, `protected/config/config_app.php`, `protected/controllers/frm`, `protected/models/frm`.

### 5.3 PreToolUse SQL

Scopo: ricordare vincoli critici quando viene usato SQL MCP.

Output consigliato:

```json
{
  "systemMessage": "SQL MCP is intended for read-only checks: inspect schema first, avoid SELECT *, parameterize/bind values, and use explain for complex queries. Do not perform mutations unless an explicitly write-capable tool and user intent allow it."
}
```

Prima iterazione: reminder non bloccante.

Possibile evoluzione futura: blocco di query distruttive se il tool input e' leggibile e contiene `INSERT`, `UPDATE`, `DELETE`, `DROP`, `ALTER`, `TRUNCATE`, salvo allowlist esplicita.

### 5.4 PreToolUse ColdFusion

Scopo: ricordare l'uso corretto di `evaluate` e del bridge runtime CF.

Output consigliato:

```json
{
  "systemMessage": "ColdFusion evaluate is for passive, small runtime probes only, mainly existing application/session/request variables. Do not use it for cfhttp, file writes, DB mutations, broad code execution, large payloads, or as a substitute for reading source code."
}
```

Prima iterazione: reminder non bloccante.

Possibile evoluzione futura: blocco di payload lunghi, mutazioni evidenti o codice non strettamente ispettivo.

## 6. Generazione e installazione manuale di hooks.json

`generate-codex-hooks.js` deve:

1. risolvere `--root` con path assoluto;
2. verificare che gli script hook attesi esistano nel repository;
3. generare un JSON valido e formattato;
4. usare comandi `node` con path assoluti verso gli script repo;
5. supportare output completo `hooks.json` e frammento gestito;
6. non leggere o modificare `~/.codex/hooks.json`;
7. non creare backup nel profilo utente;
8. stampare istruzioni brevi per installazione manuale;
9. supportare `--json` per report machine-readable;
10. fallire senza stack trace rumorosi se input o path non sono validi.

Marcatori di ownership consigliati nel JSON generato:

- path comando contenente `scripts/hooks/sophia-`;
- argomento stabile `--managed-by sophia-mcp-hooks`;
- status message con prefisso stabile `Sophia`;
- eventuale campo wrapper se supportato dal formato host, evitando comunque commenti JSON.

Esempio report:

```text
GENERATE hooks.json
ROOT E:\mcp-servers
OUTPUT stdout
OUTPUT E:\mcp-servers\codex-hooks.generated.json
MANUAL_STEP copy or merge generated hooks into ~/.codex/hooks.json
WARNING existing user hooks were not inspected or modified
```

Regole:

- non modificare hook di altri progetti;
- non assumere che `~/.codex/hooks.json` sia vuoto;
- documentare che eventuali hook esistenti devono essere preservati nel merge manuale;
- mantenere ordine leggibile degli eventi;
- se l'utente passa `--output`, scrivere nel path esplicito;
- se `--output` e' omesso, scrivere solo nel file root ignorato da git;
- se il file output esiste, non sovrascrivere senza `--force-output`.

### 6.1 Nota su config.toml

Questa micro-milestone non patcha `~/.codex/config.toml`.

Se viene usato `--check-config`, lo script puo' leggere il file e produrre solo warning:

- se `codex_hooks = true` e' presente, indicare che la feature sembra abilitata;
- se `codex_hooks = false` e' presente, indicare che gli hook potrebbero restare disabilitati;
- se lo stato non e' determinabile, indicare di verificare manualmente la configurazione Codex;
- non creare, modificare o riordinare `config.toml`.

La patch conservativa di `config.toml` resta fuori scope e va gestita in una fase M8 separata.

## 7. Generazione dei comandi portabili

Problema: `hooks.json` deve essere utente-specifico perche' contiene il path assoluto del repo.

Soluzione: generare comandi a partire da `--root`.

Regole per quoting:

- usare sempre `node "<script>" --repo-root "<root>" --managed-by sophia-mcp-hooks`;
- normalizzare path con `path.resolve`;
- su Windows escapare backslash solo nella serializzazione JSON, non nel valore logico;
- non assumere drive `D:`;
- non assumere username;
- non usare path relativi nel file utente;
- non dipendere dal current working directory.

Esempio Windows logico:

```text
node "D:\mcp-servers\scripts\hooks\sophia-user-prompt-submit.mjs" --repo-root "D:\mcp-servers" --managed-by sophia-mcp-hooks
```

Esempio Linux:

```text
node "/home/davide/mcp-servers/scripts/hooks/sophia-user-prompt-submit.mjs" --repo-root "/home/davide/mcp-servers" --managed-by sophia-mcp-hooks
```

## 8. Docs e memory: comportamento desiderato

### 8.1 Docs MCP

Gli hook non devono interrogare direttamente Docs MCP nella prima iterazione.

Devono invece ricordare all'agente di valutare Docs MCP quando il prompt ha segnali documentali o dominio-specifici.

Regola operativa da iniettare:

```text
For docs-related or domain-specific tasks, evaluate docs-mcp before independent reasoning. If search is empty, inspect tags/list documents and retry with bilingual IT/EN domain synonyms before concluding no docs exist.
```

Razionale:

- evita lookup inutili a ogni prompt;
- mantiene l'agente responsabile della decisione;
- riduce timeout e rumore;
- rende la policy esplicita anche quando l'utente non cita docs direttamente.

### 8.2 Memory MCP

Gli hook non devono interrogare direttamente Memory MCP nella prima iterazione.

Devono ricordare all'agente che memory e' un layer contestuale, non una fonte autoritativa.

Regola operativa da iniettare:

```text
For tasks involving prior decisions, repeated bugs, handoffs, constraints, or root causes, evaluate memory-mcp. Search/read memory before writing. Verify memory-derived claims against primary docs/code/tickets. Persist only reusable decisions, validated root causes, constraints, workarounds, and handoff checkpoints.
```

Razionale:

- evita duplicati di memoria;
- evita fiducia cieca in contesto obsoleto;
- favorisce project isolation;
- conserva solo conoscenza riusabile.

### 8.3 Startup Taxonomy Bootstrap

`SessionStart` carica non solo `AGENTS.md` ma inietta anche un'istruzione critica per disaccoppiare l'euristica dalla reale base di conoscenza:
```text
At the start of your task, discover the actual project knowledge taxonomy:
- Use docs_management (action: list_tags) for docs-mcp
- Use memory_list_tags and memory_list_topics for memory-mcp
Save this taxonomy to a local artifact (e.g., project_taxonomy.md)...
```
Razionale: l'agente non deve tirare a indovinare i tag o usare tag *hardcoded* negli script, ma deve basarsi sulla reale ontologia del progetto, aggiornando la mappa non appena inizia la sessione.

### 8.4 Motore Euristico e Intent Detection (`UserPromptSubmit`)

Il prompt dell'utente viene analizzato da `sophia-user-prompt-submit.mjs` usando un motore a livelli di priorità:

1.  **Intent Detection (Priorità Massima):**
    Lo script intercetta comandi operativi specifici scavalcando le regole di dominio:
    - *Question Intent:* Se il prompt è una domanda (inizia con "come", "cosa", o finisce con "?"), l'agente viene spinto a consultare la tassonomia locale e cercare in docs/memory prima di inventare risposte.
    - *Documenting Intent:* Se si chiede di "documentare", viene suggerito l'uso di `docs_management` a valle della generazione testuale.
    - *Remembering Intent:* Se si chiede di "ricordare/annotare", viene suggerito `memory_add_entry`.
2.  **Domain Search Cues (Hint contestuali):**
    Tramite `DOMAIN_SEARCH_CUES`, vengono rilevati pattern di dominio (es. *sso, migrazione, permessi*). L'hook suggerisce il concetto testuale (es. `[sso/authentication]`) ma rimanda sempre l'agente al suo artifact `project_taxonomy.md` per trovare il tag MCP esatto.
3.  **Segnali Impliciti (+2 punti):**
    Frasi come "come funziona la configurazione" o "l'ultima volta che abbiamo provato" forniscono un boost di score per innescare Docs o Memory anche se l'utente non cita esplicitamente "documentazione".
4.  **Catalog Matching:**
    Il punteggio finale somma il match sui file JSON estratti dinamicamente (`routing-catalog.json`), rilevando il contesto del repository (ColdFusion vs Yii).

### 8.5 Manutenzione e Sviluppi Futuri del Motore Euristico

Per mantenere e far evolvere correttamente l'engine di routing, attenersi a queste regole:

- **Non hardcodare i tag MCP:** Non mappare mai un pattern RegExp a un tag esatto dentro `sophia-user-prompt-submit.mjs`. Usa i "Search Cues" solo per suggerire un concetto testuale (es. `[import/integration]`) e ricorda sempre all'agente di consultare la tassonomia.
- **Ampliare l'Intent Detection:** I nuovi comandi operativi (es. "fai il deploy") vanno aggiunti in `matchIntent` in cima alla catena, in modo da avere risposte comportamentali precise.
- **Tuning dei punteggi (Threshold):** La soglia attuale di innesco per le skill è `3`. Qualsiasi match esplicito nel catalogo vale `+1` o `+5` (prompt patterns), i termini di dominio diretti valgono `+3`. I segnali impliciti valgono `+2` proprio per evitare che una singola espressione idiomatica attivi un MCP sbagliato senza altre conferme testuali.
- **Aggiornamento del Catalogo:** Le keyword automatiche delle skill e gli intenti composti derivano dal comando di setup che rigenera `routing-catalog.json`. Non toccare mai il catalog JSON a mano; modifica gli `SKILL.md` o i file JSON di configurazione e lancia `node scripts/generate-codex-hooks.js`.

## 9. Linee guida per integrare futuri MCP

Ogni nuovo MCP puo' aggiungere tre tipi di integrazione:

1. routing prompt;
2. reminder pre-tool;
3. reminder post-tool.

Non tutti i MCP hanno bisogno di tutti e tre.

### 9.1 Scheda MCP consigliata

Per ogni MCP creare una voce in un manifest locale o in una tabella documentale:

```json
{
  "id": "sql",
  "toolNamePatterns": ["mcp__sql.*", ".*sql.*"],
  "promptSignals": ["sql", "query", "schema", "database"],
  "primarySkill": "mcp-database-expert",
  "preToolReminder": "SQL MCP is intended for read-only checks...",
  "postToolReminder": null,
  "blockingPolicy": "none",
  "risk": "medium"
}
```

Campi consigliati:

| Campo | Scopo |
| --- | --- |
| `id` | identificatore stabile |
| `toolNamePatterns` | pattern per `PreToolUse` / `PostToolUse` |
| `promptSignals` | parole o regex leggere per `UserPromptSubmit` |
| `primarySkill` | skill suggerita se presente |
| `preToolReminder` | messaggio breve prima dell'uso tool |
| `postToolReminder` | messaggio breve dopo l'uso tool |
| `blockingPolicy` | `none`, `warn`, `block-dangerous` |
| `risk` | `low`, `medium`, `high` |

Per la prima iterazione, questo manifest puo' essere una costante JavaScript dentro lo script prompt router. In futuro puo' diventare JSON derivato da documentazione o skill index.

### 9.2 Criteri per aggiungere un MCP al routing

Aggiungere un MCP solo se:

- ha segnali prompt riconoscibili;
- il reminder riduce un rischio reale o migliora routing;
- il messaggio puo' stare in meno di 500 caratteri;
- non duplica interamente una skill;
- non introduce falsi positivi eccessivi;
- esiste una skill o documentazione associata, quando rilevante.

Evitare integrazioni se:

- il MCP e' raramente usato;
- il comportamento e' ovvio;
- il reminder sarebbe generico;
- il match prompt sarebbe troppo rumoroso;
- non c'e' una best practice critica da ricordare.

### 9.3 Livelli di severita'

| Livello | Comportamento | Uso consigliato |
| --- | --- | --- |
| `hint` | aggiunge contesto non vincolante | routing skill/docs/memory |
| `warn` | reminder esplicito prima/dopo tool | SQL, ColdFusion evaluate, memory write |
| `block` | blocca operazione | solo per rischi chiari e testati |

Prima iterazione: usare solo `hint` e `warn` non bloccanti.

Introdurre `block` solo dopo:

- casi reali osservati;
- test su input hook;
- allowlist/override espliciti;
- documentazione rollback;
- verifica che non rompa workflow legittimi.

## 10. Linee guida per integrare future skill

Le skill devono restare primarie nel proprio `SKILL.md`.

Gli hook possono solo suggerire:

- quale skill considerare;
- perche' potrebbe essere rilevante;
- quando non usarla.

### 10.1 Fonte dei trigger

Ordine consigliato:

1. `skills/<skill-name>/SKILL.md` come fonte primaria;
2. eventuale `docs/skills/skill-index.md` per metadati locali;
3. manifest derivato JSON generato automaticamente;
4. fallback hardcoded temporaneo negli hook solo per bootstrap.

Non usare un registry YAML manuale come nuova fonte di verita'.

### 10.2 Formato suggerimento skill

```text
Sophia routing hint: consider mcp-technical-analyst for multi-source technical reconstruction. This is non-binding; verify local AGENTS.md and relevant SKILL.md before acting.
```

Regole:

- suggerire massimo due skill;
- non suggerire skill non presenti;
- non suggerire `mcp-master-orchestrator` per ogni task complesso: usarlo solo per coordinamento multi-fase reale;
- preferire skill specialistica per task mono-dominio;
- evitare overlap tra analyst/orchestrator/specialista.

### 10.3 Skill ad alto valore iniziale

| Skill | Quando suggerire |
| --- | --- |
| `mcp-technical-analyst` | ricostruzione multi-sorgente, ticket + log + commit + docs |
| `mcp-master-orchestrator` | piani multi-fase, handoff, coordinamento tra skill |
| `mcp-code-reviewer` | review diff/PR/regressioni |
| `mcp-docs-navigator` | ricerca documentale strutturata |
| `mcp-memory-operator` | igiene memoria, consolidamento, handoff |
| `mcp-database-expert` | schema/query/report dati |
| `mcp-coldfusion-developer` | CFML, runtime CF, application scope |
| `mcp-mantis-ticket-writer` | scrittura ticket Mantis |
| `mcp-office-expert` | Word/Excel/PDF e documenti Office |

## 11. Strategia futura: manifest derivato

Quando il numero di MCP/skill cresce, evitare di hardcodare tutto negli script.

Possibile evoluzione:

```text
docs/runtime/codex-hook-routing.manifest.json
```

Generato da:

- directory `skills/*/SKILL.md`;
- eventuale `docs/skills/skill-index.md`;
- file locale `docs/runtime/mcp-routing-hints.json` per metadati MCP non esprimibili nello standard skill.

Gli hook runtime leggono il manifest generato, non decine di file.

Regole:

- manifest derivato, non fonte primaria;
- rigenerabile;
- validabile in CI/smoke;
- nessun path assoluto nel manifest repo;
- path assoluti solo in `hooks.json` utente generato.

## 11.1 Compatibilita' futura VS Code/Copilot

Per questa micro-milestone il supporto ufficiale resta Codex-only. Il generatore
`scripts/generate-codex-hooks.js` produce configurazione per `~/.codex/hooks.json`
e non deve essere riusato come file hooks VS Code/Copilot.

Per una futura compatibilita' piena VS Code/Copilot servono almeno questi
adattamenti:

| Area | Codex attuale | Futuro VS Code/Copilot |
| --- | --- | --- |
| Generatore | `generate-codex-hooks.js` | generatore separato, ad esempio `generate-copilot-hooks.js` |
| Formato config | blocchi Codex con `matcher` e `hooks` | formato host-specifico VS Code/Copilot |
| `SessionStart` | `hookSpecificOutput.additionalContext` | verificare mapping evento/source e output supportati |
| `UserPromptSubmit` | `hookSpecificOutput.additionalContext` | adattare per output supportati da VS Code/Copilot, senza assumere `additionalContext` equivalente |
| `PreToolUse` | `systemMessage` top-level e matcher su `tool_name` | gestire matcher Preview, possibilmente ignorati o meno affidabili |
| Payload evento | usa `cwd`, `prompt`, `tool_name` quando presenti | introdurre normalizzazione separata per campi Copilot |
| Test | smoke Codex standalone | fixture dedicate Copilot + test su VS Code quando possibile |

Scelta consigliata:

- mantenere gli script runtime riusabili dove il payload e' compatibile;
- isolare le differenze nel generatore e negli adapter di input/output;
- non aggiungere workaround Copilot dentro il JSON Codex;
- documentare chiaramente lo stato Preview prima di proporre installazione utente;
- introdurre Copilot solo dopo una micro-milestone dedicata con smoke e fixture
  specifiche.

## 12. Test e validazione

### 12.1 Test unitari minimi

Per `sophia-user-prompt-submit.mjs`:

- prompt senza match -> nessun output, exit 0;
- prompt docs -> output docs;
- prompt memory -> output memory;
- prompt docs + memory -> output combinato;
- prompt SQL -> suggerisce database expert / SQL reminder;
- prompt ColdFusion -> suggerisce CFML workflow;
- prompt Projectfs/rules -> suggerisce projectfs e regole condivise;
- prompt Sophia/Yii -> suggerisce Sophia/Yii workflow;
- prompt Git/Mantis -> suggerisce workflow git/mantis;
- prompt Browser/UI -> suggerisce browser automation;
- prompt Office -> suggerisce office expert;
- prompt token-heavy -> suggerisce token discipline;
- prompt sub-agent -> suggerisce `SUBAGENTS.md`;
- prompt generico CF/Yii in repo marker coerente -> suggerisce skill dominio;
- prompt generico CF/Yii in repo neutro -> nessun hint dominio;
- prompt con molti match -> massimo due suggerimenti;
- stdin vuoto o JSON invalido -> fallimento conservativo o nessun output documentato.

Per `generate-codex-hooks.js`:

- `--root` Windows -> JSON valido con path assoluti corretti;
- `--root` Linux -> JSON valido con path assoluti corretti;
- `--fragment` -> produce solo blocco gestito;
- senza `--output` -> scrive `codex-hooks.generated.json` nella root repo;
- `--output` su file nuovo -> scrive nel path esplicito;
- output esistente senza `--force-output` -> non sovrascrive;
- `--home` temporanea + `--check-config` -> produce warning/report senza modificare file;
- comandi generati includono `--managed-by sophia-mcp-hooks`;
- root temporanea con spazi nel path -> comandi quotati e path assoluti validi;
- script hook mancanti -> errore chiaro e nessuna scrittura;
- Windows path -> JSON valido;
- Linux path -> JSON valido.

Fixture documentale consigliata:

- `fixtures/hooks/existing-user-hooks.json`: esempio di `hooks.json` utente con hook non gestiti da preservare manualmente;
- `fixtures/hooks/generated-sophia-hooks.json`: output atteso del generatore.

### 12.2 Smoke manuale

```bash
node scripts/generate-codex-hooks.js --root .
node scripts/generate-codex-hooks.js --root . --force-output
node scripts/generate-codex-hooks.js --root . --fragment --output .\codex-hooks.generated.json --force-output
node scripts/generate-codex-hooks.js --root . --output .\generated\codex-hooks.json
node scripts/generate-codex-hooks.js --root . --home .\tmp-home --check-config --json
node scripts/smoke-codex-hooks.js
node scripts/hooks/sophia-user-prompt-submit.mjs --repo-root . < fixtures/hooks/prompt-docs.json
node scripts/hooks/sophia-user-prompt-submit.mjs --repo-root . < fixtures/hooks/prompt-memory.json
node scripts/hooks/sophia-user-prompt-submit.mjs --repo-root . < fixtures/hooks/prompt-empty.json
node scripts/hooks/sophia-pretool-sql.mjs --repo-root . < fixtures/hooks/pretool-sql.json
node scripts/hooks/sophia-pretool-coldfusion.mjs --repo-root . < fixtures/hooks/pretool-coldfusion.json
```

### 12.3 Done minimo

La micro-milestone e' completa quando:

- `hooks.json` viene generato con path assoluti corretti;
- il generatore non modifica `~/.codex/hooks.json`;
- senza `--output`, il file viene generato in `codex-hooks.generated.json` nella root repo;
- `codex-hooks.generated.json` e' ignorato da git;
- sovrascrittura output esistente impedita salvo `--force-output`;
- `SessionStart` produce bootstrap breve;
- `UserPromptSubmit` produce hint solo su match forti;
- SQL e ColdFusion hanno reminder non bloccanti;
- `--check-config` produce solo warning e non modifica `config.toml`;
- documentazione installazione manuale/rollback presente;
- documentazione avvisa di preservare hook utente esistenti durante il merge manuale;
- smoke test eseguiti su Windows o Linux, idealmente entrambi.

## 13. Rollback

Rollback manuale:

1. se l'utente ha creato una copia preventiva, ripristinarla:

```text
~/.codex/hooks.json.bak.<timestamp>
```

2. oppure rimuovere manualmente solo gli hook gestiti che puntano a:

```text
scripts/hooks/sophia-*.mjs
```

3. se presente, rimuovere solo il blocco/comandi con `--managed-by sophia-mcp-hooks`;
4. non cancellare l'intera directory `~/.codex`;
5. non cancellare configurazioni MCP o config TOML;
6. rigenerare il file per confrontare lo stato atteso:

```bash
node scripts/generate-codex-hooks.js --root <repo>
```

## 14. Rischi e mitigazioni

| Rischio | Mitigazione |
| --- | --- |
| Path repo cambia | rigenerare `hooks.json` con nuovo `--root` e aggiornare manualmente il profilo |
| Repo non disponibile | hook fallisce conservativamente senza bloccare |
| Troppi reminder | match forte, massimo due hint, output nullo se dubbio |
| Duplicazione regole | messaggi brevi, rimando a skill/docs |
| Drift hooks utente | script nel repo, file generato ispezionabile prima del merge manuale |
| JSON utente invalido | generatore non legge o sovrascrive il file utente; fix resta manuale |
| Falsi positivi skill | test prompt e soglie conservative |
| Hook diventa agente parallelo | niente chiamate MCP dirette nella prima iterazione |
| Hook generati ma non attivi | `--check-config` segnala stato `codex_hooks` quando verificabile, senza patch automatica |

## 15. Raccomandazione finale

Implementare questa micro-milestone come ponte leggero verso M8.

Ordine consigliato:

1. `scripts/hooks/sophia-session-start.mjs`;
2. `scripts/hooks/sophia-user-prompt-submit.mjs`;
3. `scripts/generate-codex-hooks.js`;
4. reminder SQL e ColdFusion;
5. fixture/test minimi;
6. `docs/codex-user-hooks.md`.

Tenere tutto non bloccante nella prima iterazione.

Solo dopo uso reale e raccolta di falsi positivi/negativi valutare:

- manifest derivato per routing;
- blocchi selettivi per operazioni rischiose;
- integrazione Copilot dedicata;
- installazione skill utente;
- UI/wizard della Milestone 8 completa.