failproofai 0.0.2 → 0.0.4-beta.0

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

@@ -0,0 +1,32 @@
+---
+---
+title: Список политик
+description: "Посмотрите, какие политики включены, их параметры и пользовательские политики"
+---
+
+```bash
+failproofai policies
+```
+
+Показывает все политики с их статусом, настроенными параметрами и пользовательскими политиками.
+
+## Пример вывода
+
+```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
+```
+
+Неизвестные ключи в `policyParams` здесь помечаются, чтобы вы могли рано поймать опечатки.

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

@@ -0,0 +1,43 @@
+---
+title: Удаление политик
+description: "Удаление записей hook из settings Claude Code"
+---
+
+```bash
+failproofai policies --uninstall [policy-names...] [options]
+```
+
+Удаляет записи failproofai hook из `settings.json` Claude Code.
+
+Альтернативные команды: `failproofai p -u`
+
+## Опции
+
+| Флаг | Описание |
+|------|-------------|
+| `--scope user` | Удалить из глобальных параметров (по умолчанию) |
+| `--scope project` | Удалить из параметров проекта |
+| `--scope local` | Удалить из локальных параметров |
+| `--scope all` | Удалить из всех областей одновременно |
+| `--custom` / `-c` | Очистить `customPoliciesPath` из конфига |
+
+## Поведение
+
+- **Без имён политик** - удаляет все записи failproofai hook из файла параметров
+- **С конкретными именами** - отключает эти политики, но сохраняет установленные hook
+
+## Примеры
+
+```bash
+# Удалить все hook глобально
+failproofai policies --uninstall
+
+# Отключить определённую политику (сохраняя установленные hook)
+failproofai policies --uninstall block-sudo
+
+# Удалить hook из всех областей
+failproofai policies --uninstall --scope all
+
+# Очистить путь к пользовательским политикам
+failproofai policies --uninstall --custom
+```

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

@@ -0,0 +1,12 @@
+---
+title: Проверка версии
+description: "Вывести установленную версию failproofai"
+---
+
+```bash
+failproofai --version
+# or
+failproofai -v
+```
+
+Выводит номер установленной версии.

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

@@ -0,0 +1,223 @@
+---
+---
+title: Конфигурация
+description: "Формат файла конфигурации, трёхуровневая система и правила слияния"
+icon: gear
+---
+
+failproofai использует JSON файлы конфигурации для управления активными политиками, их поведением и источниками пользовательских политик. Конфигурация разработана так, чтобы её было легко делиться с командой — закоммитьте её в репозиторий, и каждый разработчик получит одинаковую защиту агента.
+
+---
+
+## Уровни конфигурации
+
+Существует три уровня конфигурации, оцениваемые в порядке приоритета:
+
+| Уровень | Путь файла | Назначение |
+|---------|-----------|-----------|
+| **project** | `.failproofai/policies-config.json` | Настройки репозитория, коммитятся в систему контроля версий |
+| **local** | `.failproofai/policies-config.local.json` | Личные переопределения на уровне репозитория, в .gitignore |
+| **global** | `~/.failproofai/policies-config.json` | Пользовательские стандартные значения для всех проектов |
+
+Когда failproofai получает событие hook, он загружает и объединяет все три существующих файла для текущей директории.
+
+### Правила слияния
+
+**`enabledPolicies`** — объединение всех трёх уровней. Политика, активированная на любом уровне, работает.
+
+```text
+project:  ["block-sudo"]
+local:    ["block-rm-rf"]
+global:   ["block-sudo", "sanitize-api-keys"]
+
+resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← объединение без дубликатов
+```
+
+**`policyParams`** — первый уровень, определивший параметры для данной политики, полностью выигрывает. Нет глубокого слияния значений в параметрах политики.
+
+```text
+project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← выигрывает project, global игнорируется
+```
+
+```text
+project:  (нет записи block-sudo)
+local:    (нет записи block-sudo)
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← переходит на global
+```
+
+**`customPoliciesPath`** — первый уровень, определивший его, выигрывает.
+
+**`llm`** — первый уровень, определивший его, выигрывает.
+
+---
+
+## Формат файла конфигурации
+
+```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"
+}
+```
+
+---
+
+## Справка по полям
+
+### `enabledPolicies`
+
+Тип: `string[]`
+
+Список имён политик для активации. Имена должны точно совпадать с идентификаторами политик, показываемыми командой `failproofai policies`. Полный список см. в разделе [Built-in Policies](/ru/built-in-policies).
+
+Политики, отсутствующие в `enabledPolicies`, неактивны, даже если у них есть записи в `policyParams`.
+
+### `policyParams`
+
+Тип: `Record<string, Record<string, unknown>>`
+
+Переопределения параметров для каждой политики. Внешний ключ — имя политики; внутренние ключи — специфичны для политики. Каждая политика документирует свои доступные параметры в разделе [Built-in Policies](/ru/built-in-policies).
+
+Если политика имеет параметры, но вы их не указали, используются встроенные значения по умолчанию политики. Пользователи, которые вообще не конфигурируют `policyParams`, получают идентичное поведение с предыдущими версиями.
+
+Неизвестные ключи в блоке параметров политики молча игнорируются при срабатывании hook, но отмечаются как предупреждения при выполнении `failproofai policies`.
+
+#### `hint` (кросс-функциональный)
+
+Тип: `string` (опционально)
+
+Сообщение, добавляемое к причине, когда политика возвращает `deny` или `instruct`. Используйте его, чтобы дать Claude практические рекомендации без изменения самой политики.
+
+Работает с любым типом политики — встроенной, пользовательской (`custom/`), проектной конвенции (`.failproofai-project/`) или пользовательской конвенции (`.failproofai-user/`).
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Попробуйте создать свежую ветку вместо этого."
+    },
+    "block-sudo": {
+      "allowPatterns": ["sudo apt-get"],
+      "hint": "Используйте apt-get напрямую без sudo."
+    },
+    "custom/my-policy": {
+      "hint": "Сначала запросите одобрение у пользователя."
+    }
+  }
+}
+```
+
+Когда `block-force-push` запрещает, Claude видит: *"Force-pushing заблокирован. Попробуйте создать свежую ветку вместо этого."*
+
+Значения, не являющиеся строками, и пустые строки молча игнорируются. Если `hint` не установлен, поведение не изменяется (обратная совместимость).
+
+### `customPoliciesPath`
+
+Тип: `string` (абсолютный путь)
+
+Путь к JavaScript файлу, содержащему пользовательские hook политики. Устанавливается автоматически командой `failproofai policies --install --custom <path>` (путь преобразуется в абсолютный перед сохранением).
+
+Файл загружается заново при каждом события hook — кеширования нет. Детали разработки см. в разделе [Custom Policies](/ru/custom-policies).
+
+### Политики на основе конвенций (v0.0.2-beta.7+)
+
+В дополнение к явному `customPoliciesPath`, failproofai автоматически обнаруживает и загружает файлы политик из директорий `.failproofai/policies/`:
+
+| Уровень | Директория | Уровень |
+|---------|-----------|--------|
+| Project | `.failproofai/policies/` | Общая с командой через систему контроля версий |
+| User | `~/.failproofai/policies/` | Личная, применяется ко всем проектам |
+
+**Соответствие файлов:** Загружаются только файлы, соответствующие маске `*policies.{js,mjs,ts}` (например, `security-policies.mjs`, `workflow-policies.js`). Другие файлы в директории игнорируются.
+
+**Конфигурация не требуется:** Политики на основе конвенций не требуют записей в `policies-config.json`. Просто поместите файлы в директорию, и они будут обнаружены при следующем событии hook.
+
+**Загрузка объединением:** Сканируются обе директории конвенций — проектная и пользовательская. Загружаются все соответствующие файлы с обоих уровней (в отличие от `customPoliciesPath`, который использует first-scope-wins).
+
+Детали и примеры см. в разделе [Custom Policies](/ru/custom-policies).
+
+### `llm`
+
+Тип: `object` (опционально)
+
+Конфигурация LLM клиента для политик, делающих AI вызовы. Не требуется для большинства установок.
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## Управление конфигурацией через CLI
+
+Команды `policies --install` и `policies --uninstall` записывают в `settings.json` Claude Code (точки входа для hook), в то время как `policies-config.json` — это файл, который вы управляете напрямую. Это два отдельных файла:
+
+- **`settings.json`** — указывает Claude Code вызывать `failproofai --hook <event>` при каждом использовании инструмента
+- **`policies-config.json`** — указывает failproofai, какие политики оценивать и с какими параметрами
+
+Вы можете редактировать `policies-config.json` напрямую в любое время; изменения вступают в силу на следующем события hook без необходимости перезагрузки.
+
+---
+
+## Пример: конфигурация на уровне проекта с командными стандартами
+
+Закоммитьте `.failproofai/policies-config.json` в ваш репозиторий:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "block-env-files"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "hotfix"]
+    }
+  }
+}
+```
+
+Каждый разработчик может затем создать `.failproofai/policies-config.local.json` (в .gitignore) для личных переопределений без влияния на коллег.

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

@@ -0,0 +1,357 @@
+---
+title: Пользовательские политики
+description: "Напишите свои собственные политики на JavaScript - применяйте соглашения, предотвращайте дрейф, обнаруживайте сбои, интегрируйте с внешними системами"
+icon: code
+---
+
+Пользовательские политики позволяют написать правила для любого поведения агента: применять соглашения проекта, предотвращать дрейф, блокировать деструктивные операции, обнаруживать зависшие агенты или интегрироваться с Slack, рабочими процессами одобрения и многим другим. Они используют ту же систему событий перехватчиков и решения `allow`, `deny`, `instruct`, что и встроенные политики.
+
+---
+
+## Быстрый пример
+
+```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();
+  },
+});
+```
+
+Установите её:
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## Два способа загрузки пользовательских политик
+
+### Вариант 1: На основе соглашений (рекомендуется, v0.0.2-beta.7+)
+
+Поместите файлы `*policies.{js,mjs,ts}` в `.failproofai/policies/` и они будут загружены автоматически — никаких флагов или изменений конфигурации не требуется. Это работает как git hooks: поместите файл, и он просто работает.
+
+```
+# На уровне проекта — коммитится в git, делится с командой
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# На уровне пользователя — личные, применяется ко всем проектам
+~/.failproofai/policies/my-policies.mjs
+```
+
+**Как это работает:**
+- Сканируются оба каталога — проекта и пользователя (объединение — не первый приоритет)
+- Файлы загружаются в алфавитном порядке в каждом каталоге. Используйте префиксы `01-`, `02-` для управления порядком
+- Загружаются только файлы, соответствующие `*policies.{js,mjs,ts}`; остальные файлы игнорируются
+- Каждый файл загружается независимо (fail-open для каждого файла)
+- Работает вместе с явным `--custom` и встроенными политиками
+
+<Tip>
+Политики на основе соглашений — это самый простой способ поделиться политиками с командой. Закоммитьте `.failproofai/policies/` в git, и каждый член команды получит их автоматически.
+</Tip>
+
+### Вариант 2: Явный путь к файлу
+
+```bash
+# Установите с файлом пользовательских политик
+failproofai policies --install --custom ./my-policies.js
+
+# Замените путь к файлу политик
+failproofai policies --install --custom ./new-policies.js
+
+# Удалите путь к пользовательским политикам из конфигурации
+failproofai policies --uninstall --custom
+```
+
+Разрешённый абсолютный путь сохраняется в `policies-config.json` как `customPoliciesPath`. Файл загружается заново при каждом событии перехватчика — кэширования между событиями нет.
+
+### Использование обоих способов вместе
+
+Политики на основе соглашений и явный файл `--custom` могут сосуществовать. Порядок загрузки:
+
+1. Явный файл `customPoliciesPath` (если настроен)
+2. Файлы соглашений проекта (`{cwd}/.failproofai/policies/`, в алфавитном порядке)
+3. Файлы соглашений пользователя (`~/.failproofai/policies/`, в алфавитном порядке)
+
+---
+
+## API
+
+### Импорт
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+Регистрирует политику. Вызывайте столько раз, сколько нужно для нескольких политик в одном файле.
+
+```ts
+customPolicies.add({
+  name: string;                         // обязательно - уникальный идентификатор
+  description?: string;                 // отображается в выводе `failproofai policies`
+  match?: { events?: HookEventType[] }; // фильтр по типу события; опустите, чтобы совпадал все
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### Помощники для принятия решений
+
+| Функция | Эффект | Используйте когда |
+|---------|--------|------------------|
+| `allow()` | Разрешить операцию молча | Действие безопасно, сообщение не требуется |
+| `deny(message)` | Заблокировать операцию | Агент не должен выполнять это действие |
+| `instruct(message)` | Добавить контекст без блокировки | Дайте агенту дополнительный контекст для выполнения задачи |
+
+`deny(message)` — сообщение отображается Claude с префиксом `"Blocked by failproofai:"`. Один `deny` короткозамыкает всю дальнейшую оценку.
+
+`instruct(message)` — сообщение добавляется в контекст Claude для текущего вызова инструмента. Все сообщения `instruct` накапливаются и доставляются вместе.
+
+<Tip>
+Вы можете добавить дополнительные рекомендации к любому сообщению `deny` или `instruct`, добавив поле `hint` в `policyParams` — без изменения кода. Это работает для пользовательских (`custom/`), проектных (`failproofai-project/`) и пользовательских (`failproofai-user/`) политик. См. [Конфигурация → hint](/ru/configuration#hint-cross-cutting) для подробностей.
+</Tip>
+
+### Информационные сообщения allow (бета)
+
+<Note>
+`allow(message)` — это функция бета, доступная с v0.0.2-beta.3. API может измениться в будущих версиях. Более ранние версии поддерживают только `allow()` без аргументов.
+</Note>
+
+`allow(message)` разрешает операцию **и** отправляет информационное сообщение обратно Claude. Сообщение доставляется как `additionalContext` в ответе stdout обработчика перехватчика — тот же механизм, используемый `instruct`, но семантически отличается: это обновление статуса, а не предупреждение.
+
+| Функция | Эффект | Используйте когда |
+|---------|--------|------------------|
+| `allow(message)` | Разрешить и отправить контекст Claude | Подтвердить, что проверка прошла, или объяснить, почему проверка была пропущена |
+
+Варианты использования:
+- **Подтверждения статуса:** `allow("All CI checks passed.")` — указывает Claude, что всё зелено
+- **Объяснения fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — указывает Claude, почему проверка была пропущена, чтобы он имел полный контекст
+- **Несколько сообщений накапливаются:** если несколько политик возвращают `allow(message)`, все сообщения объединяются с новыми строками и доставляются вместе
+
+```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.");
+  },
+});
+```
+
+### Поля `PolicyContext`
+
+| Поле | Тип | Описание |
+|------|-----|---------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string \| undefined` | Вызываемый инструмент (например `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | Входные параметры инструмента |
+| `payload` | `Record<string, unknown>` | Полная необработанная полезная нагрузка события от Claude Code |
+| `session` | `SessionMetadata \| undefined` | Контекст сессии (см. ниже) |
+
+### Поля `SessionMetadata`
+
+| Поле | Тип | Описание |
+|------|-----|---------|
+| `sessionId` | `string` | Идентификатор сессии Claude Code |
+| `cwd` | `string` | Рабочий каталог сессии Claude Code |
+| `transcriptPath` | `string` | Путь к файлу транскрипта JSONL сессии |
+
+### Типы событий
+
+| Событие | Когда срабатывает | Содержимое `toolInput` |
+|---------|------------------|----------------------|
+| `PreToolUse` | До запуска инструмента Claude | Вход инструмента (например `{ command: "..." }` для Bash) |
+| `PostToolUse` | После завершения инструмента | Вход инструмента + `tool_result` (выход) |
+| `Notification` | Когда Claude отправляет уведомление | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - перехватчики должны всегда возвращать `allow()`, они не могут блокировать уведомления |
+| `Stop` | Когда сессия Claude заканчивается | Пусто |
+
+---
+
+## Порядок оценки
+
+Политики оцениваются в следующем порядке:
+
+1. Встроенные политики (в порядке определения)
+2. Явные пользовательские политики из `customPoliciesPath` (в порядке `.add()`)
+3. Политики соглашений из проекта `.failproofai/policies/` (файлы в алфавитном порядке, `.add()` внутри)
+4. Политики соглашений из пользователя `~/.failproofai/policies/` (файлы в алфавитном порядке, `.add()` внутри)
+
+<Note>
+Первый `deny` короткозамыкает все последующие политики. Все сообщения `instruct` накапливаются и доставляются вместе.
+</Note>
+
+---
+
+## Транзитивные импорты
+
+Файлы пользовательских политик могут импортировать локальные модули, используя относительные пути:
+
+```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");
+  },
+});
+```
+
+Все относительные импорты, достижимые из входного файла, разрешаются. Это реализуется путём переписывания импортов `from "failproofai"` на фактический путь dist и создания временных файлов `.mjs` для обеспечения совместимости ESM.
+
+---
+
+## Фильтрация по типам событий
+
+Используйте `match.events` для ограничения срабатывания политики:
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // Срабатывает только при завершении сессии
+    // ctx.session.transcriptPath содержит полный журнал сессии
+    return allow();
+  },
+});
+```
+
+Опустите `match` полностью, чтобы срабатывать на каждом типе события.
+
+---
+
+## Обработка ошибок и режимы отказа
+
+Пользовательские политики — это **fail-open**: ошибки никогда не блокируют встроенные политики и не приводят к сбою обработчика перехватчика.
+
+| Отказ | Поведение |
+|-------|----------|
+| `customPoliciesPath` не установлен | Явные пользовательские политики не запускаются; встроенные политики продолжают нормально работать |
+| Файл не найден | Предупреждение записывается в `~/.failproofai/hook.log`; встроенные политики продолжают работать |
+| Синтаксис/ошибка импорта (явная) | Ошибка записывается в `~/.failproofai/hook.log`; явные пользовательские политики пропускаются |
+| Синтаксис/ошибка импорта (соглашение) | Ошибка записывается; этот файл пропускается, другие файлы соглашений загружаются |
+| `fn` выбрасывает ошибку во время выполнения | Ошибка записывается; этот перехватчик рассматривается как `allow`; другие перехватчики продолжают работу |
+| `fn` занимает больше 10 секунд | Истечение времени ожидания записывается; рассматривается как `allow` |
+| Каталог соглашений отсутствует | Политики соглашений не запускаются; нет ошибки |
+
+<Tip>
+Для отладки ошибок пользовательских политик используйте файл журнала:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## Полный пример: несколько политик
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// Предотвращайте запись агента в каталог 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();
+  },
+});
+
+// Держите агента на правильном пути: проверьте тесты перед коммитом
+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();
+  },
+});
+
+// Предотвращайте незапланированные изменения зависимостей во время заморозки
+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 };
+```
+
+---
+
+## Примеры
+
+Каталог `examples/` содержит готовые файлы политик:
+
+| Файл | Содержимое |
+|------|-----------|
+| `examples/policies-basic.js` | Пять начальных политик, охватывающих типичные режимы отказа агента |
+| `examples/policies-advanced/index.js` | Продвинутые паттерны: транзитивные импорты, асинхронные вызовы, очистка выводов и перехватчики завершения сессии |
+| `examples/convention-policies/security-policies.mjs` | Политики безопасности на основе соглашений (блокировка записей .env, предотвращение переписывания истории git) |
+| `examples/convention-policies/workflow-policies.mjs` | Политики рабочего процесса на основе соглашений (напоминания о тестах, аудит записей файлов) |
+
+### Использование примеров явных файлов
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### Использование примеров на основе соглашений
+
+```bash
+# Скопируйте на уровень проекта
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# Или скопируйте на уровень пользователя
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+Команда установки не требуется — файлы выбираются автоматически при следующем событии перехватчика.