OmniRoute/docs/i18n/it/CLAUDE.md

# CLAUDE.md (Italiano)

🌐 **Languages:** 🇺🇸 [English](../../../CLAUDE.md) · 🇸🇦 [ar](../ar/CLAUDE.md) · 🇦🇿 [az](../az/CLAUDE.md) · 🇧🇬 [bg](../bg/CLAUDE.md) · 🇧🇩 [bn](../bn/CLAUDE.md) · 🇨🇿 [cs](../cs/CLAUDE.md) · 🇩🇰 [da](../da/CLAUDE.md) · 🇩🇪 [de](../de/CLAUDE.md) · 🇪🇸 [es](../es/CLAUDE.md) · 🇮🇷 [fa](../fa/CLAUDE.md) · 🇫🇮 [fi](../fi/CLAUDE.md) · 🇫🇷 [fr](../fr/CLAUDE.md) · 🇮🇳 [gu](../gu/CLAUDE.md) · 🇮🇱 [he](../he/CLAUDE.md) · 🇮🇳 [hi](../hi/CLAUDE.md) · 🇭🇺 [hu](../hu/CLAUDE.md) · 🇮🇩 [id](../id/CLAUDE.md) · 🇮🇩 [in](../in/CLAUDE.md) · 🇯🇵 [ja](../ja/CLAUDE.md) · 🇰🇷 [ko](../ko/CLAUDE.md) · 🇮🇳 [mr](../mr/CLAUDE.md) · 🇲🇾 [ms](../ms/CLAUDE.md) · 🇳🇱 [nl](../nl/CLAUDE.md) · 🇳🇴 [no](../no/CLAUDE.md) · 🇵🇭 [phi](../phi/CLAUDE.md) · 🇵🇱 [pl](../pl/CLAUDE.md) · 🇵🇹 [pt](../pt/CLAUDE.md) · 🇧🇷 [pt-BR](../pt-BR/CLAUDE.md) · 🇷🇴 [ro](../ro/CLAUDE.md) · 🇷🇺 [ru](../ru/CLAUDE.md) · 🇸🇰 [sk](../sk/CLAUDE.md) · 🇸🇪 [sv](../sv/CLAUDE.md) · 🇰🇪 [sw](../sw/CLAUDE.md) · 🇮🇳 [ta](../ta/CLAUDE.md) · 🇮🇳 [te](../te/CLAUDE.md) · 🇹🇭 [th](../th/CLAUDE.md) · 🇹🇷 [tr](../tr/CLAUDE.md) · 🇺🇦 [uk-UA](../uk-UA/CLAUDE.md) · 🇵🇰 [ur](../ur/CLAUDE.md) · 🇻🇳 [vi](../vi/CLAUDE.md) · 🇨🇳 [zh-CN](../zh-CN/CLAUDE.md)

---

Questo file fornisce indicazioni a Claude Code (claude.ai/code) quando si lavora con il codice in questo repository.

## Avvio Veloce

```bash
npm install                    # Installa le dipendenze (genera automaticamente .env da .env.example)
npm run dev                    # Server di sviluppo su http://localhost:20128
npm run build                  # Build di produzione (Next.js 16 standalone)
npm run lint                   # ESLint (0 errori previsti; avvisi già esistenti)
npm run typecheck:core         # Controllo TypeScript (dovrebbe essere pulito)
npm run typecheck:noimplicit:core  # Controllo rigoroso (nessun implicit any)
npm run test:coverage          # Test unitari + gate di copertura (75/75/75/70 — dichiarazioni/righe/funzioni/rami)
npm run check                  # lint + test combinati
npm run check:cycles           # Rileva dipendenze circolari
```

### Esecuzione dei Test

```bash
# Singolo file di test (runner di test nativo di Node.js — la maggior parte dei test)
node --import tsx/esm --test tests/unit/your-file.test.ts

# Vitest (server MCP, autoCombo, cache)
npm run test:vitest

# Tutti i suite
npm run test:all
```

Per la matrice completa dei test, vedere `CONTRIBUTING.md` → "Esecuzione dei Test". Per un'architettura approfondita, vedere `AGENTS.md`.

---

## Progetto a Colpo d'Occhio

**OmniRoute** — proxy/router AI unificato. Un endpoint, oltre 160 fornitori di LLM, fallback automatico.

| Livello       | Posizione               | Scopo                                                                   |
| ------------- | ----------------------- | ----------------------------------------------------------------------- |
| API Routes    | `src/app/api/v1/`       | Next.js App Router — punti di ingresso                                  |
| Handlers      | `open-sse/handlers/`    | Elaborazione delle richieste (chat, embeddings, ecc.)                   |
| Executors     | `open-sse/executors/`   | Dispatch HTTP specifico per fornitore                                   |
| Translators   | `open-sse/translator/`  | Conversione di formato (OpenAI↔Claude↔Gemini)                           |
| Transformer   | `open-sse/transformer/` | API delle risposte ↔ Completamenti Chat                                 |
| Services      | `open-sse/services/`    | Routing combinato, limiti di velocità, caching, ecc.                    |
| Database      | `src/lib/db/`           | Moduli di dominio SQLite (oltre 45 file, 55 migrazioni)                 |
| Domain/Policy | `src/domain/`           | Motore di policy, regole di costo, logica di fallback                   |
| MCP Server    | `open-sse/mcp-server/`  | 37 strumenti (30 base + 3 memoria + 4 abilità), 3 trasporti, ~13 ambiti |
| A2A Server    | `src/lib/a2a/`          | Protocollo agente JSON-RPC 2.0                                          |
| Skills        | `src/lib/skills/`       | Framework di abilità estensibile                                        |
| Memory        | `src/lib/memory/`       | Memoria conversazionale persistente                                     |

Monorepo: `src/` (app Next.js 16), `open-sse/` (workspace del motore di streaming), `electron/` (app desktop), `tests/`, `bin/` (punto di ingresso CLI).

---

## Pipeline di Richiesta

```
Client → /v1/chat/completions (rotta Next.js)
  → CORS → validazione Zod → auth? → controllo della policy → guardia contro l'iniezione del prompt
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → controllo cache → limite di frequenza → routing combo?
      → resolveComboTargets() → handleSingleModel() per target
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → retry w/ backoff
    → traduzione della risposta → stream SSE o JSON
    → Se Responses API: responsesTransformer.ts TransformStream
```

Le rotte API seguono uno schema coerente: `Roatta → preflight CORS → validazione del corpo Zod → Auth opzionale (extractApiKey/isValidApiKey) → applicazione della policy della chiave API → delega del gestore (open-sse)`. Nessun middleware globale di Next.js — l'intercettazione è specifica per rotta.

**Routing combo** (`open-sse/services/combo.ts`): 14 strategie (priorità, ponderato, riempi-primo, round-robin, P2C, casuale, meno-utilizzato, ottimizzato per costo, consapevole del reset, rigorosamente-casuale, auto, lkgp, ottimizzato per contesto, relay di contesto). Ogni target chiama `handleSingleModel()` che avvolge `handleChatCore()` con gestione degli errori per target e controlli del circuito. Vedi `docs/routing/AUTO-COMBO.md` per il punteggio Auto-Combo a 9 fattori e `docs/architecture/RESILIENCE_GUIDE.md` per i 3 livelli di resilienza.

---

## Stato di Esecuzione della Resilienza

OmniRoute ha tre meccanismi di guasto temporaneo correlati ma distinti. Mantieni il loro
ambito separato durante il debug del comportamento di routing. Vedi il
[diagramma di resilienza a 3 livelli](./docs/diagrams/exported/resilience-3layers.svg)
(fonte: [docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd))
per una mappa a colpo d'occhio.

### Interruttore di Circuito del Fornitore

**Ambito**: intero fornitore, ad esempio `glm`, `openai`, `anthropic`.

**Scopo**: fermare l'invio di traffico a un fornitore che sta ripetutamente fallendo a livello
upstream/servizio, in modo che un fornitore non sano non rallenti ogni richiesta.

**Implementazione**:

- Classe principale: `src/shared/utils/circuitBreaker.ts`
- Cablaggio di gate/esecuzione chat: `src/sse/handlers/chatHelpers.ts`, `src/sse/handlers/chat.ts`
- API di stato di esecuzione: `src/app/api/monitoring/health/route.ts`
- Wrapper condivisi: `open-sse/services/accountFallback.ts`
- Tabella di stato persistente: `domain_circuit_breakers`

**Stati**:

- `CLOSED`: il traffico normale è consentito.
- `OPEN`: il fornitore è temporaneamente bloccato; i chiamanti ricevono una risposta di circuito-fornitore-aperto
  oppure il routing combo salta a un altro target.
- `HALF_OPEN`: il timeout di reset è scaduto; consenti una richiesta di probe. Il successo chiude il
  circuito, il fallimento lo riapre.

**Predefiniti** (`open-sse/config/constants.ts`):

- Fornitori OAuth: soglia `3`, timeout di reset `60s`.
- Fornitori di chiavi API: soglia `5`, timeout di reset `30s`.
- Fornitori locali: soglia `2`, timeout di reset `15s`.

Solo gli stati di fallimento a livello di fornitore dovrebbero attivare l'interruttore del fornitore:

```ts
(408, 500, 502, 503, 504);
```

Non attivare l'interruttore dell'intero fornitore per errori normali di account/chiave/modello come la maggior parte
dei casi `401`, `403`, o `429`. Questi di solito appartengono a cooldown di connessione o lockout del modello. Un generico errore `403` del fornitore di chiavi API dovrebbe essere recuperabile a meno che non sia classificato
come errore terminale di fornitore/account.

L'interruttore utilizza un recupero pigro, non un timer in background. Quando `OPEN` scade, letture come
`getStatus()`, `canExecute()`, e `getRetryAfterMs()` aggiornano lo stato a
`HALF_OPEN`, in modo che i dashboard e i costruttori di candidati combo non continuino a escludere un
fornitore scaduto per sempre.

### Cooldown di Connessione

**Ambito**: una connessione/account/chiave del fornitore.

**Scopo**: saltare temporaneamente una chiave/account difettosa consentendo ad altre connessioni per
lo stesso fornitore di continuare a servire richieste.

**Implementazione**:

- Percorso di scrittura/aggiornamento: `src/sse/services/auth.ts::markAccountUnavailable()`
- Selezione/filtraggio dell'account: `src/sse/services/auth.ts::getProviderCredentials...`
- Calcolo del cooldown: `open-sse/services/accountFallback.ts::checkFallbackError()`
- Impostazioni: `src/lib/resilience/settings.ts`

Campi importanti sulle connessioni del fornitore:

```ts
rateLimitedUntil;
testStatus: "unavailable";
lastError;
lastErrorType;
errorCode;
backoffLevel;
```

Durante la selezione dell'account, una connessione viene saltata mentre:

```ts
new Date(rateLimitedUntil).getTime() > Date.now();
```

I cooldown sono anche pigri: quando `rateLimitedUntil` è nel passato, la connessione diventa
nuovamente idonea. All'uso riuscito, `clearAccountError()` cancella `testStatus`,
`rateLimitedUntil`, campi di errore e `backoffLevel`.

Comportamento predefinito del cooldown di connessione:

- Cooldown base OAuth: `5s`.
- Cooldown base per chiavi API: `3s`.
- `429` per chiavi API dovrebbe preferire suggerimenti di retry upstream (`Retry-After`, intestazioni di reset, o
  testo di reset analizzabile) quando disponibili.
- Fallimenti recuperabili ripetuti utilizzano un backoff esponenziale:

```ts
baseCooldownMs * 2 ** failureIndex;
```

La guardia anti-thundering-herd previene fallimenti concorrenti sulla stessa connessione da
estendere ripetutamente il cooldown o incrementare doppiamente `backoffLevel`.

Gli stati terminali non sono cooldown. `banned`, `expired`, e `credits_exhausted` sono
destinati a rimanere non disponibili fino a quando le credenziali/impostazioni non cambiano o un operatore le ripristina.
Non sovrascrivere stati terminali con stati di cooldown transitori.

### Lockout del Modello

**Ambito**: fornitore + connessione + modello.

**Scopo**: evitare di disabilitare un'intera connessione quando solo un modello è non disponibile o
limitato per quota per quella connessione.

Esempi:

- Fornitori per quota per modello che restituiscono `429`.
- Fornitori locali che restituiscono `404` per un modello mancante.
- Fallimenti di permesso di modalità/modello specifici del fornitore come le modalità Grok selezionate.

Il lockout del modello vive in `open-sse/services/accountFallback.ts` e consente alla stessa
connessione di continuare a servire altri modelli.

### Guida al Debugging

- Se tutte le chiavi per un fornitore vengono saltate, ispeziona sia lo stato dell'interruttore del fornitore che `rateLimitedUntil`/`testStatus` di ciascuna connessione.
- Se un fornitore appare permanentemente escluso dopo la finestra di reset, controlla se il codice
  sta leggendo lo stato grezzo invece di utilizzare `getStatus()`/`canExecute()`.
- Se una chiave di fornitore fallisce ma altre dovrebbero funzionare, preferisci il cooldown di connessione rispetto
  all'interruttore del fornitore.
- Se solo un modello fallisce, preferisci il lockout del modello rispetto al cooldown di connessione.
- Se uno stato dovrebbe auto-recuperarsi, dovrebbe avere un timestamp futuro/timeout di reset e un
  percorso di lettura che aggiorna lo stato scaduto. Gli stati permanenti richiedono modifiche manuali alle credenziali
  o alla configurazione.

## Convenzioni Chiave

### Stile di Codice

- **2 spazi**, punti e virgola, virgolette doppie, larghezza 100 caratteri, virgole finali es5 (imposte da lint-staged tramite Prettier)
- **Importazioni**: esterne → interne (`@/`, `@omniroute/open-sse`) → relative
- **Nomenclatura**: file=camelCase/kebab, componenti=PascalCase, costanti=UPPER_SNAKE
- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = errore ovunque; `no-explicit-any` = avviso in `open-sse/` e `tests/`
- **TypeScript**: `strict: false`, target ES2022, modulo esnext, risoluzione bundler. Preferire tipi espliciti.

### Database

- **Sempre** passare attraverso i moduli di dominio `src/lib/db/` — **mai** scrivere SQL raw in rotte o gestori
- **Mai** aggiungere logica a `src/lib/localDb.ts` (solo livello di re-export)
- **Mai** importare a barre da `localDb.ts` — importare invece moduli specifici `db/`
- Singleton DB: `getDbInstance()` da `src/lib/db/core.ts` (journaling WAL)
- Migrazioni: `src/lib/db/migrations/` — file SQL versionati, idempotenti, eseguiti in transazioni

### Gestione degli Errori

- try/catch con tipi di errore specifici, log con contesto pino
- Non nascondere errori nei flussi SSE — utilizzare segnali di abort per la pulizia
- Restituire codici di stato HTTP appropriati (4xx/5xx)

### Sicurezza

- **Mai** usare `eval()`, `new Function()`, o eval implicito
- Validare tutti gli input con schemi Zod
- Crittografare le credenziali a riposo (AES-256-GCM)
- Denylist degli header upstream: `src/shared/constants/upstreamHeaders.ts` — mantenere sanitizzazione, schemi Zod e test unitari allineati durante la modifica
- **Credenziali pubbliche upstream** (client_id/secret OAuth stile Gemini/Antigravity/Windsurf + chiavi Web Firebase estratte da CLI pubblici): **DEVONO** essere incorporate tramite `resolvePublicCred()` da `open-sse/utils/publicCreds.ts` — **mai** come stringhe letterali. Vedi `docs/security/PUBLIC_CREDS.md` per il modello obbligatorio.
- **Risposte di errore** (HTTP / SSE / gestore executor / gestore MCP): **DEVONO** passare attraverso `buildErrorBody()` o `sanitizeErrorMessage()` da `open-sse/utils/error.ts` — **mai** mettere `err.stack` o `err.message` raw nel corpo della risposta. Vedi `docs/security/ERROR_SANITIZATION.md`.
- **Comandi shell costruiti da variabili**: quando si chiama `exec()`/`spawn()` con uno script che necessita di valori di runtime, passarli tramite l'opzione `env` (automaticamente shell-escaped) — **mai** interpolare stringhe percorsi non fidati/esterni nel corpo dello script. Riferimento: `src/mitm/cert/install.ts::updateNssDatabases`.
- **Librerie sicure per impostazione predefinita** ([tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)): preferire Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink rispetto a implementazioni personalizzate ogni volta che si aggiungono nuove superfici sensibili alla sicurezza.

---

## Scenari Comuni di Modifica

### Aggiungere un Nuovo Fornitore

1. Registrare in `src/shared/constants/providers.ts` (validato da Zod al caricamento)
2. Aggiungere executor in `open-sse/executors/` se necessaria logica personalizzata (estendere `BaseExecutor`)
3. Aggiungere traduttore in `open-sse/translator/` se formato non OpenAI
4. Aggiungere configurazione OAuth in `src/lib/oauth/constants/oauth.ts` se basato su OAuth — se il CLI upstream fornisce un client_id/secret pubblico, incorporare tramite `resolvePublicCred()` (vedi `docs/security/PUBLIC_CREDS.md`), **mai** come letterale
5. Registrare modelli in `open-sse/config/providerRegistry.ts`
6. Scrivere test in `tests/unit/` (includere l'asserzione della forma publicCreds se hai aggiunto un nuovo default incorporato)

### Aggiungere una Nuova Rotta API

1. Creare directory sotto `src/app/api/v1/your-route/`
2. Creare `route.ts` con gestori `GET`/`POST`
3. Seguire il modello: CORS → validazione del corpo Zod → auth opzionale → delega del gestore
4. Il gestore va in `open-sse/handlers/` (importare da lì, non inline)
5. Le risposte di errore utilizzano `buildErrorBody()` / `errorResponse()` da `open-sse/utils/error.ts` (auto-sanitizzate — non mettere `err.stack` o `err.message` raw nel corpo). Vedi `docs/security/ERROR_SANITIZATION.md`.
6. Aggiungere test — includendo almeno un'asserzione che le risposte di errore non rivelino tracce di stack (`!body.error.message.includes("at /")`)

### Aggiungere un Nuovo Modulo DB

1. Creare `src/lib/db/yourModule.ts` — importare `getDbInstance` da `./core.ts`
2. Esportare funzioni CRUD per la tua tabella di dominio
3. Aggiungere migrazione in `src/lib/db/migrations/` se necessarie nuove tabelle
4. Re-esportare da `src/lib/localDb.ts` (aggiungere solo all'elenco di re-export)
5. Scrivere test

### Aggiungere un Nuovo Strumento MCP

1. Aggiungere definizione dello strumento in `open-sse/mcp-server/tools/` con schema di input Zod + gestore async
2. Registrare nel set di strumenti (collegato da `createMcpServer()`)
3. Assegnare agli ambiti appropriati
4. Scrivere test (invocazione dello strumento registrata nella tabella `mcp_audit`)

### Aggiungere una Nuova Abilità A2A

1. Creare abilità in `src/lib/a2a/skills/` (5 già esistenti: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
2. L'abilità riceve il contesto del compito (messaggi, metadati) → restituisce un risultato strutturato
3. Registrare in `A2A_SKILL_HANDLERS` in `src/lib/a2a/taskExecution.ts`
4. Esporre in `src/app/.well-known/agent.json/route.ts` (Agent Card)
5. Scrivere test in `tests/unit/`
6. Documentare nella tabella delle abilità in `docs/frameworks/A2A-SERVER.md`

### Aggiungere un Nuovo Agente Cloud

1. Creare classe agente in `src/lib/cloudAgent/agents/` estendendo `CloudAgentBase` (3 già esistenti: codex-cloud, devin, jules)
2. Implementare `createTask`, `getStatus`, `approvePlan`, `sendMessage`, `listSources`
3. Registrare in `src/lib/cloudAgent/registry.ts`
4. Aggiungere gestione OAuth/credenziali se necessario (`src/lib/oauth/providers/`)
5. Test + documentare in `docs/frameworks/CLOUD_AGENT.md`

### Aggiungere un Nuovo Guardrail / Eval / Abilità / Evento Webhook

- Guardrail: `src/lib/guardrails/` → documenti: `docs/security/GUARDRAILS.md`
- Suite Eval: `src/lib/evals/` → documenti: `docs/frameworks/EVALS.md`
- Abilità (sandbox): `src/lib/skills/` → documenti: `docs/frameworks/SKILLS.md`
- Evento Webhook: `src/lib/webhookDispatcher.ts` → documenti: `docs/frameworks/WEBHOOKS.md`

## Documentazione di Riferimento

Per qualsiasi modifica non banale, leggi prima il documento di approfondimento corrispondente:

| Area                                              | Documento                                                         |
| ------------------------------------------------- | ----------------------------------------------------------------- |
| Navigazione del repository                        | `docs/architecture/REPOSITORY_MAP.md`                             |
| Architettura                                      | `docs/architecture/ARCHITECTURE.md`                               |
| Riferimento ingegneristico                        | `docs/architecture/CODEBASE_DOCUMENTATION.md`                     |
| Auto-Combo (scoring a 9 fattori, 14 strategie)    | `docs/routing/AUTO-COMBO.md`                                      |
| Resilienza (3 meccanismi)                         | `docs/architecture/RESILIENCE_GUIDE.md`                           |
| Riproduzione del ragionamento                     | `docs/routing/REASONING_REPLAY.md`                                |
| Framework delle competenze                        | `docs/frameworks/SKILLS.md`                                       |
| Sistema di memoria (FTS5 + Qdrant)                | `docs/frameworks/MEMORY.md`                                       |
| Agenti cloud                                      | `docs/frameworks/CLOUD_AGENT.md`                                  |
| Guardrail (PII / injection / visione)             | `docs/security/GUARDRAILS.md`                                     |
| Credenziali pubbliche upstream (Gemini/ecc.)      | `docs/security/PUBLIC_CREDS.md`                                   |
| Sanitizzazione dei messaggi di errore             | `docs/security/ERROR_SANITIZATION.md`                             |
| Valutazioni                                       | `docs/frameworks/EVALS.md`                                        |
| Conformità / audit                                | `docs/security/COMPLIANCE.md`                                     |
| Webhook                                           | `docs/frameworks/WEBHOOKS.md`                                     |
| Pipeline di autorizzazione                        | `docs/architecture/AUTHZ_GUIDE.md`                                |
| Stealth (TLS / impronta digitale)                 | `docs/security/STEALTH_GUIDE.md`                                  |
| Protocolli degli agenti (A2A / ACP / Cloud)       | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`                        |
| Server MCP                                        | `docs/frameworks/MCP-SERVER.md`                                   |
| Server A2A                                        | `docs/frameworks/A2A-SERVER.md`                                   |
| Riferimento API + OpenAPI                         | `docs/reference/API_REFERENCE.md` + `docs/reference/openapi.yaml` |
| Catalogo dei fornitori (generato automaticamente) | `docs/reference/PROVIDER_REFERENCE.md`                            |
| Flusso di rilascio                                | `docs/ops/RELEASE_CHECKLIST.md`                                   |

---

## Test

| Cosa                    | Comando                                                                   |
| ----------------------- | ------------------------------------------------------------------------- |
| Test unitari            | `npm run test:unit`                                                       |
| Singolo file            | `node --import tsx/esm --test tests/unit/file.test.ts`                    |
| Vitest (MCP, autoCombo) | `npm run test:vitest`                                                     |
| E2E (Playwright)        | `npm run test:e2e`                                                        |
| Protocol E2E (MCP+A2A)  | `npm run test:protocols:e2e`                                              |
| Ecosistema              | `npm run test:ecosystem`                                                  |
| Porta di copertura      | `npm run test:coverage` (75/75/75/70 — dichiarazioni/righe/funzioni/rami) |
| Rapporto di copertura   | `npm run coverage:report`                                                 |

**Regola PR**: Se modifichi il codice di produzione in `src/`, `open-sse/`, `electron/`, o `bin/`, devi includere o aggiornare i test nella stessa PR.

**Preferenza per il livello di test**: unità prima → integrazione (multi-modulo o stato DB) → e2e (solo UI/flusso di lavoro). Codifica le riproduzioni di bug come test automatizzati prima o insieme alla correzione.

**Politica di copertura di Copilot**: Quando una PR modifica il codice di produzione e la copertura è inferiore al 75% (dichiarazioni/righe/funzioni) o al 70% (rami), non limitarti a segnalare — aggiungi o aggiorna i test, riesegui la porta di copertura, poi chiedi conferma. Includi i comandi eseguiti, i file di test modificati e il risultato finale della copertura nel rapporto PR.

---

## Flusso di lavoro Git

```bash
# Non impegnarti mai direttamente su main
git checkout -b feat/your-feature
git commit -m "feat: descrivi la tua modifica"
git push -u origin feat/your-feature
```

**Prefissi dei branch**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`

**Formato del commit** (Conventional Commits): `feat(db): aggiungi circuit breaker` — scope: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`

**Hook di Husky**:

- **pre-commit**: lint-staged + `check-docs-sync` + `check:any-budget:t11`
- **pre-push**: `npm run test:unit`

---

## Ambiente

- **Runtime**: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES Modules
- **TypeScript**: 5.9+, target ES2022, module esnext, risoluzione bundler
- **Alias di percorso**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*`
- **Porta predefinita**: 20128 (API + dashboard sulla stessa porta)
- **Directory dei dati**: variabile d'ambiente `DATA_DIR`, predefinita a `~/.omniroute/`
- **Variabili d'ambiente chiave**: `PORT`, `JWT_SECRET`, `API_KEY_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL`
- Configurazione: `cp .env.example .env` poi genera `JWT_SECRET` (`openssl rand -base64 48`) e `API_KEY_SECRET` (`openssl rand -hex 32`)

---

## Regole Rigide

1. Non impegnare mai segreti o credenziali
2. Non aggiungere mai logica a `localDb.ts`
3. Non usare mai `eval()` / `new Function()` / eval implicito
4. Non impegnarsi mai direttamente su `main`
5. Non scrivere mai SQL raw nelle route — usa i moduli in `src/lib/db/`
6. Non ignorare mai silenziosamente gli errori nei flussi SSE
7. Validare sempre gli input con gli schemi Zod
8. Includere sempre test quando si modifica il codice di produzione
9. La copertura deve rimanere ≥75% (dichiarazioni, righe, funzioni) / ≥70% (rami). Misurato attualmente: ~82%.
10. Non bypassare mai gli hook di Husky (`--no-verify`, `--no-gpg-sign`) senza esplicita approvazione dell'operatore.
11. Non incorporare mai client_id/secret OAuth pubblici upstream o chiavi Web Firebase come stringhe letterali — passare sempre attraverso `resolvePublicCred()` (`open-sse/utils/publicCreds.ts`). Vedi `docs/security/PUBLIC_CREDS.md`.
12. Non restituire mai `err.stack` / `err.message` raw nelle risposte HTTP / SSE / executor — instradare sempre attraverso `buildErrorBody()` o `sanitizeErrorMessage()` (`open-sse/utils/error.ts`). Vedi `docs/security/ERROR_SANITIZATION.md`.
13. Non interpolare mai stringhe percorsi esterni o valori di runtime in script shell passati a `exec()`/`spawn()` — passare invece tramite l'opzione `env`. Riferimento: `src/mitm/cert/install.ts::updateNssDatabases`.
14. Non ignorare mai un avviso CodeQL / Secret-Scanning senza (a) controllare prima la documentazione del pattern sopra per vedere se l'aiuto si applica, e (b) registrare la giustificazione tecnica nel commento di dismissione. Precedente: `js/stack-trace-exposure` sollevato su callsites che già instradano attraverso `sanitizeErrorMessage()` è una limitazione nota di CodeQL (sanitizzatori personalizzati non riconosciuti) — dismettere come `false positive` facendo riferimento a `docs/security/ERROR_SANITIZATION.md`.
15. Non esporre mai route che generano processi figlio (`/api/mcp/`, `/api/cli-tools/runtime/`) senza classificazione `isLocalOnlyPath()` in `src/server/authz/routeGuard.ts`. L'applicazione del loopback avviene incondizionatamente prima di qualsiasi controllo di autenticazione — un JWT trapelato tramite tunnel non può attivare la generazione di processi. Vedi `docs/security/ROUTE_GUARD_TIERS.md`.
16. Non includere mai trailer `Co-Authored-By` che accreditano un assistente AI, LLM o account di automazione (es. nomi contenenti "Claude", "GPT", "Copilot", "Bot"; email su `anthropic.com` / `openai.com` / indirizzi `noreply.github.com` di proprietà di bot). Tali trailer indirizzano l'attribuzione del commit all'account del bot su GitHub, nascondendo l'autore reale (`diegosouzapw`) nella cronologia della PR. I collaboratori umani — inclusi gli autori di PR upstream e i segnalatori di issue portati in OmniRoute — POSSONO e DEVONO essere accreditati con trailer standard `Co-authored-by: Name <email>`; i workflow di port upstream (`/port-upstream-features`, `/port-upstream-issues`) ne dipendono.