failproofai 0.0.2 → 0.0.3

package/.next/standalone/docs/it/cli/list-policies.mdx

@@ -0,0 +1,31 @@
+---
+title: Elenca policies
+description: "Visualizza quali policy sono abilitate, i loro parametri e le policy personalizzate"
+---
+
+```bash
+failproofai policies
+```
+
+Mostra tutte le policy con il loro stato, i parametri configurati e le policy personalizzate.
+
+## Output di esempio
+
+```text
+Failproof AI Hook Policies (user)
+
+  Status  Name                          Description
+  ──────  ──────────────────────────────────────────────────────────────
+  ✓       block-sudo                    Block sudo commands
+            allowPatterns: ["sudo systemctl status"]
+  ✓       block-rm-rf                   Block recursive deletions
+  ✗       block-curl-pipe-sh            Block curl|bash patterns
+  ✓       sanitize-api-keys             Redact API keys from output
+            additionalPatterns: [{ regex: "MY_TOKEN_...", label: "..." }]
+
+  ── Custom Policies (/home/alice/myproject/my-policies.js) ──────────────
+  ✓       require-jira-ticket           Block commits without ticket
+  ✓       approval-gate                 Approval gate for destructive ops
+```
+
+Le chiavi sconosciute in `policyParams` vengono segnalate qui in modo che tu possa rilevare gli errori di battitura in anticipo.

package/.next/standalone/docs/it/cli/remove-policies.mdx

@@ -0,0 +1,44 @@
+---
+title: Disinstallare le policies
+description: "Rimuovere le voci hook dalle impostazioni di Claude Code"
+---
+
+```bash
+failproofai policies --uninstall [policy-names...] [options]
+```
+
+Rimuove le voci hook di failproofai dal file `settings.json` di Claude Code.
+
+Alias: `failproofai p -u`
+
+## Opzioni
+
+| Flag | Descrizione |
+|------|-------------|
+| `--scope user` | Rimuove dalle impostazioni globali (predefinito) |
+| `--scope project` | Rimuove dalle impostazioni del progetto |
+| `--scope local` | Rimuove dalle impostazioni locali |
+| `--scope all` | Rimuove da tutti gli ambiti contemporaneamente |
+| `--custom` / `-c` | Cancella il percorso `customPoliciesPath` dalla configurazione |
+| `--beta` | Rimuove solo le policy beta dalla configurazione |
+
+## Comportamento
+
+- **Nessun nome di policy** - rimuove tutte le voci hook di failproofai dal file di impostazioni
+- **Nomi specifici** - disabilita quelle policy ma mantiene gli hook installati
+
+## Esempi
+
+```bash
+# Rimuove tutti gli hook globalmente
+failproofai policies --uninstall
+
+# Disabilita una policy specifica (mantiene gli hook installati)
+failproofai policies --uninstall block-sudo
+
+# Rimuove gli hook da ogni ambito
+failproofai policies --uninstall --scope all
+
+# Cancella il percorso delle policy personalizzate
+failproofai policies --uninstall --custom
+```

package/.next/standalone/docs/it/cli/version.mdx

@@ -0,0 +1,12 @@
+---
+title: Controlla versione
+description: "Stampa la versione installata di failproofai"
+---
+
+```bash
+failproofai --version
+# or
+failproofai -v
+```
+
+Stampa il numero della versione installata.

package/.next/standalone/docs/it/configuration.mdx

@@ -0,0 +1,223 @@
+---
+---
+title: Configurazione
+description: "Formato del file di configurazione, sistema a tre scope e regole di merge"
+icon: gear
+---
+
+failproofai utilizza file di configurazione JSON per controllare quali policy sono attive, come si comportano e da dove vengono caricate le policy personalizzate. La configurazione è progettata per essere facilmente condivisibile con il tuo team - committila nel tuo repository e ogni sviluppatore avrà la stessa rete di sicurezza per gli agenti.
+
+---
+
+## Scope di configurazione
+
+Esistono tre scope di configurazione, valutati in ordine di priorità:
+
+| Scope | Percorso del file | Scopo |
+|-------|------------------|-------|
+| **project** | `.failproofai/policies-config.json` | Impostazioni per-repository, committate nel controllo di versione |
+| **local** | `.failproofai/policies-config.local.json` | Override personali per-repository, gitignored |
+| **global** | `~/.failproofai/policies-config.json` | Impostazioni predefinite a livello di utente su tutti i progetti |
+
+Quando failproofai riceve un evento hook, carica e unisce tutti e tre i file che esistono per la directory di lavoro corrente.
+
+### Regole di merge
+
+**`enabledPolicies`** - l'unione di tutti e tre gli scope. Una policy abilitata a qualsiasi livello è attiva.
+
+```text
+project:  ["block-sudo"]
+local:    ["block-rm-rf"]
+global:   ["block-sudo", "sanitize-api-keys"]
+
+resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← unione deduplicated
+```
+
+**`policyParams`** - il primo scope che definisce i parametri per una determinata policy vince completamente. Non c'è alcun deep merging dei valori all'interno dei parametri di una policy.
+
+```text
+project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← project vince, global ignorato
+```
+
+```text
+project:  (no block-sudo entry)
+local:    (no block-sudo entry)
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← ricade a global
+```
+
+**`customPoliciesPath`** - il primo scope che lo definisce vince.
+
+**`llm`** - il primo scope che lo definisce vince.
+
+---
+
+## Formato del file di configurazione
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "sanitize-jwt",
+    "block-env-files",
+    "block-read-outside-cwd"
+  ],
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+    },
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "prod"]
+    },
+    "block-rm-rf": {
+      "allowPaths": ["/tmp"]
+    },
+    "block-read-outside-cwd": {
+      "allowPaths": ["/shared/data", "/opt/company"]
+    },
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
+      ]
+    },
+    "warn-large-file-write": {
+      "thresholdKb": 512
+    }
+  },
+  "customPoliciesPath": "/home/alice/myproject/my-policies.js"
+}
+```
+
+---
+
+## Riferimento dei campi
+
+### `enabledPolicies`
+
+Type: `string[]`
+
+Elenco dei nomi delle policy da abilitare. I nomi devono corrispondere esattamente agli identificatori delle policy mostrati da `failproofai policies`. Vedi [Built-in Policies](/it/built-in-policies) per l'elenco completo.
+
+Le policy non in `enabledPolicies` sono inattive, anche se hanno voci in `policyParams`.
+
+### `policyParams`
+
+Type: `Record<string, Record<string, unknown>>`
+
+Override dei parametri per-policy. La chiave esterna è il nome della policy; le chiavi interne sono specifiche della policy. Ogni policy documenta i suoi parametri disponibili in [Built-in Policies](/it/built-in-policies).
+
+Se una policy ha parametri ma non li specifichi, vengono utilizzati i valori predefiniti integrati della policy. Gli utenti che non configurano affatto `policyParams` ottengono un comportamento identico alle versioni precedenti.
+
+Le chiavi sconosciute all'interno del blocco parametri di una policy vengono silenziosamente ignorate al momento dell'attivazione dell'hook ma segnalate come avvisi quando esegui `failproofai policies`.
+
+#### `hint` (cross-cutting)
+
+Type: `string` (optional)
+
+Un messaggio aggiunto al motivo quando una policy restituisce `deny` o `instruct`. Usalo per dare a Claude una guida praticabile senza modificare la policy stessa.
+
+Funziona con qualsiasi tipo di policy — integrata, personalizzata (`custom/`), convenzione di progetto (`.failproofai-project/`), o convenzione utente (`.failproofai-user/`).
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Try creating a fresh branch instead."
+    },
+    "block-sudo": {
+      "allowPatterns": ["sudo apt-get"],
+      "hint": "Use apt-get directly without sudo."
+    },
+    "custom/my-policy": {
+      "hint": "Ask the user for approval first."
+    }
+  }
+}
+```
+
+Quando `block-force-push` nega, Claude vede: *"Force-pushing is blocked. Try creating a fresh branch instead."*
+
+I valori non stringa e le stringhe vuote vengono silenziosamente ignorate. Se `hint` non è impostato, il comportamento non cambia (retrocompatibile).
+
+### `customPoliciesPath`
+
+Type: `string` (absolute path)
+
+Percorso a un file JavaScript contenente policy hook personalizzate. Viene impostato automaticamente da `failproofai policies --install --custom <path>` (il percorso viene risolto a assoluto prima di essere archiviato).
+
+Il file viene caricato nuovo su ogni evento hook - non c'è caching. Vedi [Custom Policies](/it/custom-policies) per i dettagli di authoring.
+
+### Policy basate su convenzione (v0.0.2-beta.7+)
+
+Oltre al `customPoliciesPath` esplicito, failproofai scopre e carica automaticamente i file di policy dalle directory `.failproofai/policies/`:
+
+| Livello | Directory | Scope |
+|---------|-----------|-------|
+| Project | `.failproofai/policies/` | Condiviso con il team via controllo di versione |
+| User | `~/.failproofai/policies/` | Personale, si applica a tutti i progetti |
+
+**File matching:** Solo i file corrispondenti a `*policies.{js,mjs,ts}` vengono caricati (ad es. `security-policies.mjs`, `workflow-policies.js`). Gli altri file nella directory vengono ignorati.
+
+**Nessuna configurazione necessaria:** Le policy di convenzione non richiedono voci in `policies-config.json`. Basta eliminare i file nella directory e verranno raccolti al prossimo evento hook.
+
+**Union loading:** Entrambe le directory di convenzione di progetto e utente vengono scansionate. Tutti i file corrispondenti da entrambi i livelli vengono caricati (a differenza di `customPoliciesPath` che utilizza first-scope-wins).
+
+Vedi [Custom Policies](/it/custom-policies) per ulteriori dettagli ed esempi.
+
+### `llm`
+
+Type: `object` (optional)
+
+Configurazione del client LLM per le policy che effettuano chiamate AI. Non richiesto per la maggior parte delle configurazioni.
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## Gestione della configurazione da CLI
+
+I comandi `policies --install` e `policies --uninstall` scrivono nel `settings.json` di Claude Code (i punti di ingresso dell'hook), mentre `policies-config.json` è il file che gestisci direttamente. I due sono separati:
+
+- **`settings.json`** - dice a Claude Code di chiamare `failproofai --hook <event>` su ogni tool use
+- **`policies-config.json`** - dice a failproofai quali policy valutare e con quali parametri
+
+Puoi modificare `policies-config.json` direttamente in qualsiasi momento; le modifiche hanno effetto immediatamente al prossimo evento hook senza necessità di riavvio.
+
+---
+
+## Esempio: config a livello di progetto con impostazioni predefinite del team
+
+Committa `.failproofai/policies-config.json` nel tuo repo:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "block-env-files"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "hotfix"]
+    }
+  }
+}
+```
+
+Ogni sviluppatore può quindi creare `.failproofai/policies-config.local.json` (gitignored) per override personali senza influenzare i compagni di squadra.

package/.next/standalone/docs/it/custom-policies.mdx

@@ -0,0 +1,358 @@
+---
+---
+title: Criteri Personalizzati
+description: "Scrivi i tuoi criteri in JavaScript - applica convenzioni, previeni deviazioni, rilevai guasti, integra con sistemi esterni"
+icon: code
+---
+
+I criteri personalizzati ti permettono di scrivere regole per qualsiasi comportamento dell'agente: applica convenzioni di progetto, previeni deviazioni, blocca operazioni distruttive, rileva agenti bloccati, o integra con Slack, flussi di approvazione e altro. Usano lo stesso sistema di eventi hook e le decisioni `allow`, `deny`, `instruct` dei criteri integrati.
+
+---
+
+## Esempio rapido
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "no-production-writes",
+  description: "Block writes to paths containing 'production'",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("production")) {
+      return deny("Writes to production paths are blocked");
+    }
+    return allow();
+  },
+});
+```
+
+Installalo:
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## Due modi per caricare criteri personalizzati
+
+### Opzione 1: Basata su convenzione (consigliato, v0.0.2-beta.7+)
+
+Inserisci i file `*policies.{js,mjs,ts}` in `.failproofai/policies/` e vengono caricati automaticamente — nessun flag o modifica di configurazione necessaria. Funziona come i git hook: inserisci un file e funziona.
+
+```
+# Livello di progetto — incluso in git, condiviso con il team
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# Livello utente — personale, si applica a tutti i progetti
+~/.failproofai/policies/my-policies.mjs
+```
+
+**Come funziona:**
+- Entrambe le directory di progetto e utente vengono scansionate (unione — non primo ambito vince)
+- I file vengono caricati alfabeticamente all'interno di ogni directory. Aggiungi il prefisso `01-`, `02-` per controllare l'ordine
+- Solo i file che corrispondono a `*policies.{js,mjs,ts}` vengono caricati; gli altri file vengono ignorati
+- Ogni file viene caricato indipendentemente (fail-open per file)
+- Funziona insieme ai criteri espliciti `--custom` e integrati
+
+<Tip>
+I criteri di convenzione sono il modo più semplice per condividere criteri tra un team. Includi `.failproofai/policies/` in git e ogni membro del team li otterrà automaticamente.
+</Tip>
+
+### Opzione 2: Percorso file esplicito
+
+```bash
+# Installa con un file di criteri personalizzati
+failproofai policies --install --custom ./my-policies.js
+
+# Sostituisci il percorso del file di criteri
+failproofai policies --install --custom ./new-policies.js
+
+# Rimuovi il percorso dei criteri personalizzati dalla configurazione
+failproofai policies --uninstall --custom
+```
+
+Il percorso assoluto risolto viene memorizzato in `policies-config.json` come `customPoliciesPath`. Il file viene caricato di nuovo ad ogni evento hook - non c'è caching tra gli eventi.
+
+### Usare entrambi insieme
+
+I criteri di convenzione e il file esplicito `--custom` possono coesistere. Ordine di caricamento:
+
+1. File `customPoliciesPath` esplicito (se configurato)
+2. File di convenzione di progetto (`{cwd}/.failproofai/policies/`, alfabetici)
+3. File di convenzione utente (`~/.failproofai/policies/`, alfabetici)
+
+---
+
+## API
+
+### Importazione
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+Registra un criterio. Chiama questo tutte le volte che necessario per più criteri nello stesso file.
+
+```ts
+customPolicies.add({
+  name: string;                         // obbligatorio - identificatore univoco
+  description?: string;                 // mostrato nell'output di `failproofai policies`
+  match?: { events?: HookEventType[] }; // filtra per tipo di evento; ometti per corrispondere a tutti
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### Helper di decisione
+
+| Funzione | Effetto | Usa quando |
+|----------|--------|----------|
+| `allow()` | Consenti l'operazione silenziosamente | L'azione è sicura, nessun messaggio necessario |
+| `deny(message)` | Blocca l'operazione | L'agente non dovrebbe compiere questa azione |
+| `instruct(message)` | Aggiungi contesto senza bloccare | Dai all'agente contesto aggiuntivo per rimanere in traccia |
+
+`deny(message)` - il messaggio viene visualizzato a Claude con prefisso `"Blocked by failproofai:"`. Un singolo `deny` fa corto circuito di tutta la valutazione ulteriore.
+
+`instruct(message)` - il messaggio viene aggiunto al contesto di Claude per la chiamata dello strumento corrente. Tutti i messaggi `instruct` vengono accumulati e consegnati insieme.
+
+<Tip>
+Puoi aggiungere guidance extra a qualsiasi messaggio `deny` o `instruct` aggiungendo un campo `hint` in `policyParams` — nessuna modifica di codice necessaria. Questo funziona per i criteri personalizzati (`custom/`), di convenzione di progetto (`.failproofai-project/`), e di convenzione utente (`.failproofai-user/`) anche. Vedi [Configurazione → hint](/it/configuration#hint-cross-cutting) per i dettagli.
+</Tip>
+
+### Messaggi di allow informativi (beta)
+
+<Note>
+`allow(message)` è una funzione beta disponibile da v0.0.2-beta.3. L'API potrebbe cambiare nelle versioni future. Le versioni precedenti supportano solo `allow()` senza argomenti.
+</Note>
+
+`allow(message)` consente l'operazione **e** invia un messaggio informativo indietro a Claude. Il messaggio viene consegnato come `additionalContext` nella risposta stdout del gestore dell'evento hook — lo stesso meccanismo usato da `instruct`, ma semanticamente diverso: è un aggiornamento di stato, non un avviso.
+
+| Funzione | Effetto | Usa quando |
+|----------|--------|----------|
+| `allow(message)` | Consenti e invia contesto a Claude | Conferma che un controllo è passato, o spiega perché un controllo è stato saltato |
+
+Casi d'uso:
+- **Conferme di stato:** `allow("All CI checks passed.")` — dice a Claude che tutto è verde
+- **Spiegazioni fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — dice a Claude perché un controllo è stato saltato così ha il contesto completo
+- **Più messaggi si accumulano:** se più criteri ciascuno restituisce `allow(message)`, tutti i messaggi sono uniti con newline e consegnati insieme
+
+```js
+customPolicies.add({
+  name: "confirm-branch-status",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    const cwd = ctx.session?.cwd;
+    if (!cwd) return allow("No working directory, skipping branch check.");
+
+    // ... check branch status ...
+    if (allPushed) {
+      return allow("Branch is up to date with remote.");
+    }
+    return deny("Unpushed changes detected.");
+  },
+});
+```
+
+### Campi `PolicyContext`
+
+| Campo | Tipo | Descrizione |
+|-------|------|-------------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string \| undefined` | Lo strumento che viene chiamato (es. `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | I parametri di input dello strumento |
+| `payload` | `Record<string, unknown>` | Payload di evento grezzo completo da Claude Code |
+| `session` | `SessionMetadata \| undefined` | Contesto di sessione (vedi sotto) |
+
+### Campi `SessionMetadata`
+
+| Campo | Tipo | Descrizione |
+|-------|------|-------------|
+| `sessionId` | `string` | Identificatore di sessione Claude Code |
+| `cwd` | `string` | Directory di lavoro della sessione Claude Code |
+| `transcriptPath` | `string` | Percorso al file transcript JSONL della sessione |
+
+### Tipi di evento
+
+| Evento | Quando si attiva | Contenuti `toolInput` |
+|-------|--------------|----------------------|
+| `PreToolUse` | Prima che Claude esegua uno strumento | L'input dello strumento (es. `{ command: "..." }` per Bash) |
+| `PostToolUse` | Dopo che uno strumento si completa | L'input dello strumento + `tool_result` (l'output) |
+| `Notification` | Quando Claude invia una notifica | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - i hook devono sempre restituire `allow()`, non possono bloccare le notifiche |
+| `Stop` | Quando la sessione Claude termina | Vuoto |
+
+---
+
+## Ordine di valutazione
+
+I criteri vengono valutati in questo ordine:
+
+1. Criteri integrati (in ordine di definizione)
+2. Criteri personalizzati espliciti da `customPoliciesPath` (in ordine `.add()`)
+3. Criteri di convenzione da `.failproofai/policies/` di progetto (file alfabetici, ordine `.add()` interno)
+4. Criteri di convenzione da `~/.failproofai/policies/` utente (file alfabetici, ordine `.add()` interno)
+
+<Note>
+Il primo `deny` fa corto circuito di tutti i criteri successivi. Tutti i messaggi `instruct` vengono accumulati e consegnati insieme.
+</Note>
+
+---
+
+## Importazioni transitive
+
+I file di criteri personalizzati possono importare moduli locali usando percorsi relativi:
+
+```js
+// my-policies.js
+import { isBlockedPath } from "./utils.js";
+import { checkApproval } from "./approval-client.js";
+
+customPolicies.add({
+  name: "approval-gate",
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
+    return approved ? allow() : deny("Approval required for this command");
+  },
+});
+```
+
+Tutte le importazioni relative raggiungibili dal file di entry vengono risolte. Questo viene implementato riscrivendo le importazioni `from "failproofai"` al percorso dist effettivo e creando file `.mjs` temporanei per assicurare la compatibilità ESM.
+
+---
+
+## Filtraggio del tipo di evento
+
+Usa `match.events` per limitare quando un criterio si attiva:
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // Si attiva solo quando la sessione termina
+    // ctx.session.transcriptPath contiene il log di sessione completo
+    return allow();
+  },
+});
+```
+
+Ometti `match` interamente per attivarsi su ogni tipo di evento.
+
+---
+
+## Gestione degli errori e modalità di errore
+
+I criteri personalizzati sono **fail-open**: gli errori non bloccano mai i criteri integrati o causano crash del gestore dell'hook.
+
+| Errore | Comportamento |
+|---------|----------|
+| `customPoliciesPath` non impostato | Nessun criterio personalizzato esplicito viene eseguito; i criteri di convenzione e integrati continuano normalmente |
+| File non trovato | Avviso registrato su `~/.failproofai/hook.log`; i criteri integrati continuano |
+| Errore di sintassi/importazione (esplicito) | Errore registrato su `~/.failproofai/hook.log`; criteri personalizzati espliciti saltati |
+| Errore di sintassi/importazione (convenzione) | Errore registrato; quel file saltato, altri file di convenzione ancora caricati |
+| `fn` lancia al runtime | Errore registrato; quel hook trattato come `allow`; altri hook continuano |
+| `fn` impiega più di 10s | Timeout registrato; trattato come `allow` |
+| Directory di convenzione mancante | Nessun criterio di convenzione viene eseguito; nessun errore |
+
+<Tip>
+Per eseguire il debug degli errori di criteri personalizzati, guarda il file di log:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## Esempio completo: più criteri
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// Evita che l'agente scriva nella directory secrets/
+customPolicies.add({
+  name: "block-secrets-dir",
+  description: "Prevent agent from writing to secrets/ directory",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
+    return allow();
+  },
+});
+
+// Tieni l'agente in traccia: verifica i test prima di committare
+customPolicies.add({
+  name: "remind-test-before-commit",
+  description: "Keep the agent on track: verify tests pass before committing",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    if (/git\s+commit/.test(cmd)) {
+      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
+    }
+    return allow();
+  },
+});
+
+// Previeni modifiche non pianificate alle dipendenze durante il freeze
+customPolicies.add({
+  name: "dependency-freeze",
+  description: "Prevent unplanned dependency changes during freeze period",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
+    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
+      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
+    }
+    return allow();
+  },
+});
+
+export { customPolicies };
+```
+
+---
+
+## Esempi
+
+La directory `examples/` contiene file di criteri pronti all'uso:
+
+| File | Contenuti |
+|------|----------|
+| `examples/policies-basic.js` | Cinque criteri iniziali che coprono modalità di errore comuni dell'agente |
+| `examples/policies-advanced/index.js` | Schemi avanzati: importazioni transitive, chiamate asincrone, scrubbing di output, e hook di fine sessione |
+| `examples/convention-policies/security-policies.mjs` | Criteri di sicurezza basati su convenzione (blocca scritture .env, previeni riscrittura della cronologia git) |
+| `examples/convention-policies/workflow-policies.mjs` | Criteri di flusso di lavoro basati su convenzione (promemoria di test, file di scrittura di audit) |
+
+### Uso di esempi di file espliciti
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### Uso di esempi basati su convenzione
+
+```bash
+# Copia a livello di progetto
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# Oppure copia a livello di utente
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+Nessun comando di installazione necessario — i file vengono prelevati automaticamente al prossimo evento hook.