failproofai 0.0.2 → 0.0.3

package/.next/standalone/docs/pt-br/cli/list-policies.mdx

@@ -0,0 +1,31 @@
+---
+title: Listar políticas
+description: "Veja quais políticas estão habilitadas, seus parâmetros e políticas personalizadas"
+---
+
+```bash
+failproofai policies
+```
+
+Exibe todas as políticas com seu status, parâmetros configurados e políticas personalizadas.
+
+## Exemplo de saída
+
+```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
+```
+
+Chaves desconhecidas em `policyParams` são sinalizadas aqui para que você possa identificar erros de digitação com antecedência.

package/.next/standalone/docs/pt-br/cli/remove-policies.mdx

@@ -0,0 +1,44 @@
+---
+title: Desinstalar políticas
+description: "Remover entradas de hook das configurações do Claude Code"
+---
+
+```bash
+failproofai policies --uninstall [policy-names...] [options]
+```
+
+Remove entradas de hook do failproofai do `settings.json` do Claude Code.
+
+Aliases: `failproofai p -u`
+
+## Opções
+
+| Flag | Descrição |
+|------|-----------|
+| `--scope user` | Remover das configurações globais (padrão) |
+| `--scope project` | Remover das configurações do projeto |
+| `--scope local` | Remover das configurações locais |
+| `--scope all` | Remover de todos os escopos de uma vez |
+| `--custom` / `-c` | Limpar o `customPoliciesPath` da configuração |
+| `--beta` | Remover apenas as políticas beta da configuração |
+
+## Comportamento
+
+- **Sem nomes de política** — remove todas as entradas de hook do failproofai do arquivo de configurações
+- **Nomes específicos** — desativa essas políticas, mas mantém os hooks instalados
+
+## Exemplos
+
+```bash
+# Remover todos os hooks globalmente
+failproofai policies --uninstall
+
+# Desativar uma política específica (mantém os hooks instalados)
+failproofai policies --uninstall block-sudo
+
+# Remover hooks de todos os escopos
+failproofai policies --uninstall --scope all
+
+# Limpar o caminho de políticas personalizadas
+failproofai policies --uninstall --custom
+```

package/.next/standalone/docs/pt-br/cli/version.mdx

@@ -0,0 +1,12 @@
+---
+title: Verificar versão
+description: "Exibe a versão instalada do failproofai"
+---
+
+```bash
+failproofai --version
+# ou
+failproofai -v
+```
+
+Exibe o número da versão instalada.

package/.next/standalone/docs/pt-br/configuration.mdx

@@ -0,0 +1,222 @@
+---
+title: Configuração
+description: "Formato do arquivo de configuração, sistema de três escopos e regras de mesclagem"
+icon: gear
+---
+
+failproofai usa arquivos de configuração JSON para controlar quais políticas estão ativas, como elas se comportam e de onde as políticas personalizadas são carregadas. A configuração foi pensada para ser fácil de compartilhar com o time — faça commit dela no seu repositório e todos os desenvolvedores terão a mesma rede de segurança para agentes.
+
+---
+
+## Escopos de configuração
+
+Existem três escopos de configuração, avaliados em ordem de prioridade:
+
+| Escopo | Caminho do arquivo | Finalidade |
+|--------|-------------------|------------|
+| **project** | `.failproofai/policies-config.json` | Configurações por repositório, commitadas no controle de versão |
+| **local** | `.failproofai/policies-config.local.json` | Substituições pessoais por repositório, ignoradas pelo git |
+| **global** | `~/.failproofai/policies-config.json` | Padrões do usuário para todos os projetos |
+
+Quando failproofai recebe um evento de hook, ele carrega e mescla os três arquivos que existirem para o diretório de trabalho atual.
+
+### Regras de mesclagem
+
+**`enabledPolicies`** — a união dos três escopos. Uma política habilitada em qualquer nível fica ativa.
+
+```text
+project:  ["block-sudo"]
+local:    ["block-rm-rf"]
+global:   ["block-sudo", "sanitize-api-keys"]
+
+resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← união sem duplicatas
+```
+
+**`policyParams`** — o primeiro escopo que define os parâmetros de uma determinada política vence por completo. Não há mesclagem profunda dos valores dentro dos parâmetros de uma política.
+
+```text
+project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← project vence, global é ignorado
+```
+
+```text
+project:  (sem entrada block-sudo)
+local:    (sem entrada block-sudo)
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← recai para o global
+```
+
+**`customPoliciesPath`** — o primeiro escopo que o define vence.
+
+**`llm`** — o primeiro escopo que o define vence.
+
+---
+
+## Formato do arquivo de configuração
+
+```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"
+}
+```
+
+---
+
+## Referência de campos
+
+### `enabledPolicies`
+
+Tipo: `string[]`
+
+Lista de nomes de políticas a habilitar. Os nomes devem corresponder exatamente aos identificadores de política exibidos por `failproofai policies`. Consulte [Políticas integradas](/pt-br/built-in-policies) para a lista completa.
+
+Políticas ausentes de `enabledPolicies` ficam inativas, mesmo que possuam entradas em `policyParams`.
+
+### `policyParams`
+
+Tipo: `Record<string, Record<string, unknown>>`
+
+Substituições de parâmetros por política. A chave externa é o nome da política; as chaves internas são específicas de cada política. Cada política documenta seus parâmetros disponíveis em [Políticas integradas](/pt-br/built-in-policies).
+
+Se uma política possui parâmetros mas você não os especifica, os valores padrão da política são utilizados. Usuários que não configuram `policyParams` têm comportamento idêntico ao das versões anteriores.
+
+Chaves desconhecidas dentro do bloco de parâmetros de uma política são silenciosamente ignoradas no momento de disparo do hook, mas sinalizadas como avisos ao executar `failproofai policies`.
+
+#### `hint` (transversal)
+
+Tipo: `string` (opcional)
+
+Uma mensagem anexada ao motivo quando uma política retorna `deny` ou `instruct`. Use-o para fornecer orientações acionáveis ao Claude sem modificar a própria política.
+
+Funciona com qualquer tipo de política — integrada, personalizada (`custom/`), convenção de projeto (`.failproofai-project/`) ou convenção de usuário (`.failproofai-user/`).
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Tente criar um branch novo em vez disso."
+    },
+    "block-sudo": {
+      "allowPatterns": ["sudo apt-get"],
+      "hint": "Use apt-get diretamente sem sudo."
+    },
+    "custom/my-policy": {
+      "hint": "Peça aprovação ao usuário primeiro."
+    }
+  }
+}
+```
+
+Quando `block-force-push` nega, Claude recebe: *"Force-pushing está bloqueado. Tente criar um branch novo em vez disso."*
+
+Valores não textuais e strings vazias são silenciosamente ignorados. Se `hint` não estiver definido, o comportamento permanece inalterado (compatível com versões anteriores).
+
+### `customPoliciesPath`
+
+Tipo: `string` (caminho absoluto)
+
+Caminho para um arquivo JavaScript contendo políticas de hook personalizadas. Esse campo é definido automaticamente por `failproofai policies --install --custom <path>` (o caminho é resolvido para absoluto antes de ser armazenado).
+
+O arquivo é carregado novamente a cada evento de hook — não há cache. Consulte [Políticas personalizadas](/pt-br/custom-policies) para detalhes de autoria.
+
+### Políticas baseadas em convenção (v0.0.2-beta.7+)
+
+Além do `customPoliciesPath` explícito, failproofai descobre e carrega automaticamente arquivos de políticas dos diretórios `.failproofai/policies/`:
+
+| Nível | Diretório | Escopo |
+|-------|-----------|--------|
+| Projeto | `.failproofai/policies/` | Compartilhado com o time via controle de versão |
+| Usuário | `~/.failproofai/policies/` | Pessoal, aplica-se a todos os projetos |
+
+**Correspondência de arquivos:** Apenas arquivos que correspondam a `*policies.{js,mjs,ts}` são carregados (por exemplo, `security-policies.mjs`, `workflow-policies.js`). Outros arquivos no diretório são ignorados.
+
+**Sem necessidade de configuração:** Políticas de convenção não exigem entradas em `policies-config.json`. Basta adicionar os arquivos ao diretório e eles serão detectados no próximo evento de hook.
+
+**Carregamento por união:** Os diretórios de convenção do projeto e do usuário são varridos. Todos os arquivos correspondentes de ambos os níveis são carregados (ao contrário de `customPoliciesPath`, que usa o primeiro escopo vencedor).
+
+Consulte [Políticas personalizadas](/pt-br/custom-policies) para mais detalhes e exemplos.
+
+### `llm`
+
+Tipo: `object` (opcional)
+
+Configuração do cliente LLM para políticas que fazem chamadas de IA. Não é necessário para a maioria dos casos.
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## Gerenciando a configuração pela CLI
+
+Os comandos `policies --install` e `policies --uninstall` escrevem no `settings.json` do Claude Code (os pontos de entrada do hook), enquanto `policies-config.json` é o arquivo que você gerencia diretamente. Os dois são separados:
+
+- **`settings.json`** — instrui o Claude Code a chamar `failproofai --hook <event>` a cada uso de ferramenta
+- **`policies-config.json`** — instrui o failproofai sobre quais políticas avaliar e com quais parâmetros
+
+Você pode editar `policies-config.json` diretamente a qualquer momento; as alterações entram em vigor imediatamente no próximo evento de hook, sem necessidade de reinicialização.
+
+---
+
+## Exemplo: configuração no nível do projeto com padrões do time
+
+Faça commit de `.failproofai/policies-config.json` no seu repositório:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "block-env-files"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "hotfix"]
+    }
+  }
+}
+```
+
+Cada desenvolvedor pode então criar `.failproofai/policies-config.local.json` (ignorado pelo git) para substituições pessoais sem afetar os colegas de time.

package/.next/standalone/docs/pt-br/custom-policies.mdx

@@ -0,0 +1,357 @@
+---
+title: Políticas Personalizadas
+description: "Escreva suas próprias políticas em JavaScript - aplique convenções, previna desvios, detecte falhas, integre com sistemas externos"
+icon: code
+---
+
+As políticas personalizadas permitem que você escreva regras para qualquer comportamento do agente: aplicar convenções do projeto, prevenir desvios, controlar operações destrutivas, detectar agentes travados ou integrar com Slack, fluxos de aprovação e muito mais. Elas usam o mesmo sistema de eventos de hook e as decisões `allow`, `deny`, `instruct` das políticas embutidas.
+
+---
+
+## Exemplo rápido
+
+```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();
+  },
+});
+```
+
+Instale:
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## Duas formas de carregar políticas personalizadas
+
+### Opção 1: Baseada em convenção (recomendada, v0.0.2-beta.7+)
+
+Coloque arquivos `*policies.{js,mjs,ts}` dentro de `.failproofai/policies/` e eles serão carregados automaticamente — sem flags ou alterações de configuração. Funciona como git hooks: coloque o arquivo e pronto.
+
+```
+# Nível do projeto — commitado no git, compartilhado com o time
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# Nível do usuário — pessoal, aplicado a todos os projetos
+~/.failproofai/policies/my-policies.mjs
+```
+
+**Como funciona:**
+- Tanto o diretório do projeto quanto o do usuário são escaneados (união — não prevalece o primeiro escopo encontrado)
+- Os arquivos são carregados em ordem alfabética dentro de cada diretório. Use prefixos `01-`, `02-` para controlar a ordem
+- Apenas arquivos que correspondem a `*policies.{js,mjs,ts}` são carregados; outros arquivos são ignorados
+- Cada arquivo é carregado de forma independente (fail-open por arquivo)
+- Funciona junto com `--custom` explícito e políticas embutidas
+
+<Tip>
+As políticas por convenção são a forma mais fácil de compartilhar políticas com um time. Faça commit de `.failproofai/policies/` no git e todos os membros do time as recebem automaticamente.
+</Tip>
+
+### Opção 2: Caminho de arquivo explícito
+
+```bash
+# Instalar com um arquivo de políticas personalizado
+failproofai policies --install --custom ./my-policies.js
+
+# Substituir o caminho do arquivo de políticas
+failproofai policies --install --custom ./new-policies.js
+
+# Remover o caminho de políticas personalizadas da configuração
+failproofai policies --uninstall --custom
+```
+
+O caminho absoluto resolvido é armazenado em `policies-config.json` como `customPoliciesPath`. O arquivo é carregado novamente a cada evento de hook — não há cache entre eventos.
+
+### Usando as duas opções juntas
+
+As políticas por convenção e o arquivo `--custom` explícito podem coexistir. Ordem de carregamento:
+
+1. Arquivo `customPoliciesPath` explícito (se configurado)
+2. Arquivos de convenção do projeto (`{cwd}/.failproofai/policies/`, ordem alfabética)
+3. Arquivos de convenção do usuário (`~/.failproofai/policies/`, ordem alfabética)
+
+---
+
+## API
+
+### Importação
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+Registra uma política. Chame quantas vezes forem necessárias para múltiplas políticas no mesmo arquivo.
+
+```ts
+customPolicies.add({
+  name: string;                         // obrigatório - identificador único
+  description?: string;                 // exibido na saída de `failproofai policies`
+  match?: { events?: HookEventType[] }; // filtra por tipo de evento; omita para corresponder a todos
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### Helpers de decisão
+
+| Função | Efeito | Use quando |
+|--------|--------|------------|
+| `allow()` | Permite a operação silenciosamente | A ação é segura, nenhuma mensagem é necessária |
+| `deny(message)` | Bloqueia a operação | O agente não deve executar esta ação |
+| `instruct(message)` | Adiciona contexto sem bloquear | Fornece contexto adicional ao agente para mantê-lo no caminho certo |
+
+`deny(message)` — a mensagem aparece para Claude com o prefixo `"Blocked by failproofai:"`. Um único `deny` interrompe toda avaliação posterior.
+
+`instruct(message)` — a mensagem é anexada ao contexto de Claude para a chamada de ferramenta atual. Todas as mensagens `instruct` são acumuladas e entregues juntas.
+
+<Tip>
+Você pode adicionar orientações extras a qualquer mensagem `deny` ou `instruct` incluindo um campo `hint` em `policyParams` — sem necessidade de alteração de código. Isso funciona para políticas personalizadas (`custom/`), de convenção do projeto (`.failproofai-project/`) e de convenção do usuário (`.failproofai-user/`) também. Veja [Configuração → hint](/pt-br/configuration#hint-cross-cutting) para detalhes.
+</Tip>
+
+### Mensagens informativas de allow (beta)
+
+<Note>
+`allow(message)` é um recurso beta disponível desde a v0.0.2-beta.3. A API pode mudar em versões futuras. Versões anteriores suportam apenas `allow()` sem argumentos.
+</Note>
+
+`allow(message)` permite a operação **e** envia uma mensagem informativa de volta para Claude. A mensagem é entregue como `additionalContext` na resposta stdout do handler de hook — o mesmo mecanismo usado por `instruct`, mas semanticamente diferente: é uma atualização de status, não um aviso.
+
+| Função | Efeito | Use quando |
+|--------|--------|------------|
+| `allow(message)` | Permite e envia contexto para Claude | Confirmar que uma verificação passou, ou explicar por que foi ignorada |
+
+Casos de uso:
+- **Confirmações de status:** `allow("All CI checks passed.")` — informa Claude que tudo está ok
+- **Explicações de fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — informa Claude por que uma verificação foi ignorada, para que tenha contexto completo
+- **Múltiplas mensagens se acumulam:** se várias políticas retornarem `allow(message)`, todas as mensagens são unidas com quebras de linha e entregues juntas
+
+```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.");
+  },
+});
+```
+
+### Campos de `PolicyContext`
+
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string \| undefined` | A ferramenta sendo chamada (ex.: `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | Os parâmetros de entrada da ferramenta |
+| `payload` | `Record<string, unknown>` | Payload bruto completo do evento do Claude Code |
+| `session` | `SessionMetadata \| undefined` | Contexto da sessão (veja abaixo) |
+
+### Campos de `SessionMetadata`
+
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| `sessionId` | `string` | Identificador da sessão do Claude Code |
+| `cwd` | `string` | Diretório de trabalho da sessão do Claude Code |
+| `transcriptPath` | `string` | Caminho para o arquivo de transcrição JSONL da sessão |
+
+### Tipos de evento
+
+| Evento | Quando dispara | Conteúdo de `toolInput` |
+|--------|---------------|------------------------|
+| `PreToolUse` | Antes de Claude executar uma ferramenta | A entrada da ferramenta (ex.: `{ command: "..." }` para Bash) |
+| `PostToolUse` | Após a conclusão de uma ferramenta | A entrada da ferramenta + `tool_result` (a saída) |
+| `Notification` | Quando Claude envia uma notificação | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks devem sempre retornar `allow()`, não podem bloquear notificações |
+| `Stop` | Quando a sessão Claude encerra | Vazio |
+
+---
+
+## Ordem de avaliação
+
+As políticas são avaliadas nesta ordem:
+
+1. Políticas embutidas (na ordem de definição)
+2. Políticas personalizadas explícitas do `customPoliciesPath` (na ordem de `.add()`)
+3. Políticas de convenção do projeto `.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` dentro de cada arquivo)
+4. Políticas de convenção do usuário `~/.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` dentro de cada arquivo)
+
+<Note>
+O primeiro `deny` interrompe todas as políticas subsequentes. Todas as mensagens `instruct` são acumuladas e entregues juntas.
+</Note>
+
+---
+
+## Importações transitivas
+
+Arquivos de políticas personalizadas podem importar módulos locais usando caminhos relativos:
+
+```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");
+  },
+});
+```
+
+Todas as importações relativas acessíveis a partir do arquivo de entrada são resolvidas. Isso é implementado reescrevendo as importações de `from "failproofai"` para o caminho real do dist e criando arquivos `.mjs` temporários para garantir compatibilidade com ESM.
+
+---
+
+## Filtragem por tipo de evento
+
+Use `match.events` para limitar quando uma política é disparada:
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // Dispara apenas quando a sessão encerra
+    // ctx.session.transcriptPath contém o log completo da sessão
+    return allow();
+  },
+});
+```
+
+Omita `match` completamente para disparar em todos os tipos de evento.
+
+---
+
+## Tratamento de erros e modos de falha
+
+As políticas personalizadas são **fail-open**: erros nunca bloqueiam as políticas embutidas nem causam crash no handler de hook.
+
+| Falha | Comportamento |
+|-------|---------------|
+| `customPoliciesPath` não definido | Nenhuma política personalizada explícita é executada; políticas de convenção e embutidas continuam normalmente |
+| Arquivo não encontrado | Aviso registrado em `~/.failproofai/hook.log`; políticas embutidas continuam |
+| Erro de sintaxe/importação (explícito) | Erro registrado em `~/.failproofai/hook.log`; políticas personalizadas explícitas são ignoradas |
+| Erro de sintaxe/importação (convenção) | Erro registrado; aquele arquivo é ignorado, outros arquivos de convenção ainda são carregados |
+| `fn` lança erro em tempo de execução | Erro registrado; aquele hook é tratado como `allow`; outros hooks continuam |
+| `fn` demora mais de 10s | Timeout registrado; tratado como `allow` |
+| Diretório de convenção ausente | Nenhuma política de convenção é executada; sem erro |
+
+<Tip>
+Para depurar erros de políticas personalizadas, monitore o arquivo de log:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## Exemplo completo: múltiplas políticas
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// Impede o agente de escrever no diretório 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();
+  },
+});
+
+// Mantém o agente no caminho certo: verifica testes antes de commitar
+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();
+  },
+});
+
+// Previne alterações de dependências não planejadas durante o período de congelamento
+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 };
+```
+
+---
+
+## Exemplos
+
+O diretório `examples/` contém arquivos de políticas prontos para uso:
+
+| Arquivo | Conteúdo |
+|---------|----------|
+| `examples/policies-basic.js` | Cinco políticas iniciais cobrindo modos de falha comuns de agentes |
+| `examples/policies-advanced/index.js` | Padrões avançados: importações transitivas, chamadas assíncronas, limpeza de saída e hooks de fim de sessão |
+| `examples/convention-policies/security-policies.mjs` | Políticas de segurança baseadas em convenção (bloquear escritas em .env, impedir reescrita do histórico git) |
+| `examples/convention-policies/workflow-policies.mjs` | Políticas de fluxo de trabalho baseadas em convenção (lembretes de testes, auditoria de escritas em arquivos) |
+
+### Usando exemplos com arquivo explícito
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### Usando exemplos baseados em convenção
+
+```bash
+# Copiar para o nível do projeto
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# Ou copiar para o nível do usuário
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+Nenhum comando de instalação é necessário — os arquivos são detectados automaticamente no próximo evento de hook.