# 01 — Executive summary

Audit del 2026-07-19 su `master` (`e953d358`) e `origin/hooks-routing-llm` (`b1f3a31a`). Metodo: 6 subagenti economici/intermedi per estrazione meccanica, sintesi e decisioni del main agent. Evidenze: raw JSON + `11-evidence-index.csv`.

## Stato generale

Il framework è **sano, con debito mirato**. 21 skill con ruoli chiari (2 orchestrator, 2 analyst, 14 specialist, 2 sidecar, 1 repository-only), routing deterministico testato in CI (25 casi + 16 engineCases + smoke), fallback robusti, guardrail di sicurezza dati reali e in gran parte enforced lato server. Non emerge alcuna necessità di redesign: i problemi sono concentrati in tre cluster ben delimitati.

**Cluster 1 — Governance dei dati di routing (il rischio principale).** La mappa skill→dominio esiste in 4-5 superfici manutenute a mano indipendentemente: AGENTS.md, GLOBAL.md (stale: 11 voci su 21 skill), frontmatter delle SKILL.md → catalogo generato, e tabelle `DOMAIN_KEYWORDS`/`SKILL_HINTS` hardcoded nel hook che *sovrastano* il catalogo (+3 vs +1). La matrice decisionale dell'orchestrator omette 8 skill esistenti; il drift tra queste superfici è già osservabile ed è silenzioso. Nota distinta *(corretta 2026-07-20)*: `mcp-runtime-integrator` è assente dal catalogo runtime, ma la guida viva (riga 68) la dichiara "repository-only, non distribuibile nei runtime utente" — è quindi un **confine distributivo intenzionale da documentare e testare**, non un drift (SKAUD-001, P3). *(Correzione 2026-07-19: il finding originario "6 description frontmatter malformate" era un falso positivo dell'estrattore delegato — verificato eseguendo il generatore del catalogo; v. `12-audit-corrections.md`.)*

**Cluster 2 — Skill che compensano contratti tool deboli.** 21 istanze documentate in cui le SKILL.md sostituiscono metadata che dovrebbero stare nei tool MCP: il caso più critico è `cf_bridge.evaluate` — *(corretto 2026-07-20)* il lato ColdFusion ha già una denylist deterministica (`mcp_agent.cfm:134-139`), ma non è una sandbox completa (bypass e funzioni non elencate restano possibili) e il contratto MCP-side non dichiara nulla: il guardrail nella skill è difesa in profondità, non unica barriera. Seguono i mega-tool (`browser_session` 38 azioni, `docs_management` 20 azioni) che impongono alle skill sequenze obbligatorie fragili, e l'assenza di dry-run/backup in office-node compensata da "copia prima di scrivere". Nuovo finding correlato: il **token di fallback del bridge CF è condiviso e hardcoded** in client Node, file CFM e `.env.example` (SKAUD-027) — rischio basso finché il bridge resta su localhost, reale se esposto in rete. Non sono compensazioni per modelli deboli: servono a *qualunque* modello finché i contratti non migliorano. `memory-node` e `analytics-node` dimostrano già il pattern corretto (error code stabili, annotations, two-step delete): va replicato.

**Cluster 3 — Eval che misurano conformità, non outcome.** Copertura nominale 100% e 15 file eval con outcome *dichiarato* nei fixture documentali, ma **zero outcome eseguito e verificato automaticamente**: nessun runner esegue i casi contro un modello e ne giudica il risultato; persino la validazione sintattica non è in CI. Il sistema oggi non può rispondere con dati alla propria domanda esistenziale: "le skill migliorano davvero il risultato?". La priorità corretta è quindi infrastruttura prima dei casi: schema eval v2 + runner (SKAUD-013), poi migrazione dei casi (SKAUD-025).

## Bottleneck rispetto a modelli più capaci

Le istruzioni classificate MODEL_COMPENSATION (da sottoporre ad ablation, non rimuovere): la spinta del frontmatter dell'orchestrator a intercettare anche l'analisi tecnica (decomposizione potenzialmente superflua per un frontier), la token discipline rigida duplicata in 2 file, e il sistema stesso di keyword curate. La maggior parte delle regole, però, è INVARIANT/POLICY/TOOL_CONTRACT: il framework non microgestisce i modelli, suggerisce (hint cap 2, mai enforcement del routing) — un'architettura già compatibile con l'autonomia crescente. Verdetto: il rischio bottleneck è **contenuto e localizzato**, non sistemico.

## Il branch candidato

Il nome inganna: **non introduce routing LLM**. È lo scaffolding deterministico (metadata semantici validati, catalogo MCP con availability, ambiguity gate spento di default, contract+policy resolver puri e non cablati) per un futuro valutatore descritto solo nel design doc. Zero chiamate di rete, fail-closed ovunque, equivalenza byte-identica con master testata, rollback banale. Risolve problemi reali (osservabilità del ranking via candidateScores, fonte semantica versionata). Introduce 4 problemi minori: telemetria promessa ma non cablata (la shadow mode sarebbe cieca), resolver dichiarato solo nel design doc, cambio di policy `test-affected` fuori tema, nuovo stato persistente senza version. Nessuno è bloccante.

## Dieci priorità (riviste 2026-07-19)

1. **SKAUD-019** (P1, pre-merge): decidere sul cambio test-affected prima del merge del branch.
2. **SKAUD-004** (P1, pre-merge): dichiarare il policy resolver come scaffolding.
3. **SKAUD-003** (P1, post-merge/pre-shadow): cablare ambiguity/candidateScores nella telemetria.
4. **SKAUD-005+006** (P1): schema eval divergente + wiring validazione in CI.
5. **SKAUD-013** (P1): eval schema v2 + runner eseguibile (prerequisito outcome), poi SKAUD-025 per i casi.
6. **SKAUD-014** (P1): harness ablation secondo specifica + esecuzione ABL-02/09/10/13.
7. **SKAUD-002** (P1): anti-trigger per database-expert.
8. **SKAUD-023** (P2): consolidare DOMAIN_KEYWORDS/SKILL_HINTS nei semantic overrides (post-merge).
9. **SKAUD-017/018/027** (P2): error code per git/sql-node; description/annotation conservative del tool `cf_bridge` intero (le annotation MCP sono per-tool, non per-action); migrazione del token di fallback CF. Separazione tool + security review denylist = SKAUD-026.
10. **SKAUD-007/008** (P2): matrice orchestrator completa + deprecazione Minimal skill map.

## Rischi per il merge

Quasi nulli sul piano tecnico (nessuna sovrapposizione di file con master, 1 solo commit divergente doc-only). Il merge dello scaffolding **non richiede** la telemetria ambiguity, perché il gate è disabilitato e il resolver non è cablato; la telemetria diventa obbligatoria prima dell'attivazione della shadow mode (SKAUD-003, post-merge). Il principale rischio di *processo* pre-merge resta il cambio fuori tema a `test-affected.mjs` (SKAUD-019), da non accettare silenziosamente.

## Confidenza e raccomandazione

Confidenza complessiva **ALTA** sui fatti (tutto verificato su file e righe), **MEDIA** sulle classificazioni MODEL_COMPENSATION (per definizione richiedono ablation). Raccomandazione: completare i due interventi pre-merge SKAUD-019 e SKAUD-004, quindi mergiare il branch candidato; pianificare SKAUD-003 e SKAUD-020 prima della shadow mode. Eseguire le prime 5 PR del piano sotto e trattare il consolidamento delle fonti di routing come tema dei prossimi 2 cicli — è l'unico debito che peggiora da solo col tempo.

---

## Verdetto complessivo

**HEALTHY_WITH_TARGETED_DEBT**

## Verdetto branch candidato

**READY_WITH_GUARDRAILS** — guardrail *pre-merge* effettivi (rivisti): decisione su test-affected (SKAUD-019) e dichiarazione scaffolding (SKAUD-004). La telemetria ambiguity (SKAUD-003) e la version del manifest (SKAUD-020) sono requisiti **post-merge/pre-shadow**, non di merge: con gate disabilitato e resolver non cablato il merge non attiva nulla. Fasi complete in `06-*.md` §Requisiti riclassificati.

## Prime cinque PR (riviste 2026-07-19 — una PR = un task coeso)

| Ordine | Obiettivo | Branch base | File | Rischio | Modello implementatore | Modello reviewer |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | SKAUD-019: decisione test-affected (revert o motivazione) | hooks-routing-llm | scripts/test-affected.mjs, tests/test-affected.test.mjs | Basso | ECONOMIC | FABLE_REQUIRED |
| 2 | SKAUD-004: dichiarazione scaffolding policy resolver (doc-only) → poi merge del branch | hooks-routing-llm | routing-policy-resolver.mjs (commento), guida viva | Nullo | ECONOMIC | INTERMEDIATE |
| 3 | SKAUD-005: riallineamento schema eval mantis-test-writer | master | skills/mcp-mantis-test-writer/evals/evals.json | Basso | ECONOMIC | INTERMEDIATE |
| 4 | SKAUD-006: wiring check-skill-evals in npm test (+ validazione shape) | master | package.json, scripts/check-skill-evals-json.js | Basso | ECONOMIC | INTERMEDIATE |
| 5 | SKAUD-002: sezione routing/anti-trigger per database-expert | master | skills/mcp-database-expert/SKILL.md | Basso | ECONOMIC | INTERMEDIATE |

Successive immediate (post-merge): SKAUD-003 (telemetria, pre-shadow), SKAUD-013 (schema v2 + runner), SKAUD-027 (token fallback bridge CF).

## Elementi da non modificare

I 10 punti con evidenze sono in `09-do-not-change.md`: enforcement SQL read-only; guardrail cf_bridge nella skill (finché il tool non ha guard); two-step delete analytics; igiene memoria; copy-before-write office; dry-run docs; fallback deterministici del routing; default fail-closed del branch; pattern legacy action/project_path/save_path e `.env` dal progetto target; anti-trigger reciproci simmetrici (e nota private di mantis).

## Decisioni ancora aperte

1. **Se e quando implementare il valutatore semantico reale** (Ministral/Ollama): decisione di prodotto/costo che il repo non può risolvere; prerequisito informativo: dati della fase shadow (dipende da SKAUD-003).
2. **Soglie dell'ambiguity gate**: tarabili solo con telemetria reale, non decidibili staticamente.
3. **Classificazione definitiva delle MODEL_COMPENSATION** (token discipline, spinta a orchestrare): richiede l'esecuzione degli ablation ABL-02/09/10/13 (SKAUD-014).
4. **Evoluzione di `cf_bridge`** (SKAUD-026): separazione in tool distinti (`cf_evaluate`/`cf_logs_list`/`cf_logs_read`) con annotation per-tool corrette e security review della denylist esistente — richiede analisi di compatibilità client, non decidibile dal solo repo.
5. **Destino dei `.codex/agents/*.toml` committati** (gitignore vs check anti-hand-edit): dipende da come i client li consumano a runtime, non verificabile dal solo repo.