failproofai 0.0.2 → 0.0.4-beta.0

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

@@ -0,0 +1,31 @@
+---
+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/ja/cli/remove-policies.mdx

@@ -0,0 +1,43 @@
+---
+title: ポリシーのアンインストール
+description: "Claude Code の設定からフックエントリを削除する"
+---
+
+```bash
+failproofai policies --uninstall [policy-names...] [options]
+```
+
+Claude Code の `settings.json` から failproofai フックエントリを削除します。
+
+エイリアス: `failproofai p -u`
+
+## オプション
+
+| フラグ | 説明 |
+|------|-------------|
+| `--scope user` | グローバル設定から削除（デフォルト） |
+| `--scope project` | プロジェクト設定から削除 |
+| `--scope local` | ローカル設定から削除 |
+| `--scope all` | すべてのスコープから一括削除 |
+| `--custom` / `-c` | 設定から `customPoliciesPath` をクリアする |
+
+## 動作
+
+- **ポリシー名を指定しない場合** — 設定ファイルからすべての failproofai フックエントリを削除します
+- **特定の名前を指定した場合** — 対象のポリシーを無効化しますが、フックのインストール状態は維持されます
+
+## 使用例
+
+```bash
+# グローバルからすべてのフックを削除する
+failproofai policies --uninstall
+
+# 特定のポリシーを無効化する（フックはインストールしたまま）
+failproofai policies --uninstall block-sudo
+
+# すべてのスコープからフックを削除する
+failproofai policies --uninstall --scope all
+
+# カスタムポリシーのパスをクリアする
+failproofai policies --uninstall --custom
+```

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

@@ -0,0 +1,12 @@
+---
+title: バージョンを確認する
+description: "インストール済みの failproofai バージョンを表示する"
+---
+
+```bash
+failproofai --version
+# or
+failproofai -v
+```
+
+インストール済みのバージョン番号を表示します。

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

@@ -0,0 +1,222 @@
+---
+title: 設定
+description: "設定ファイルのフォーマット、3スコープシステム、マージルール"
+icon: gear
+---
+
+failproofai は JSON 設定ファイルを使用して、どのポリシーが有効か、その動作方法、カスタムポリシーの読み込み元を管理します。設定はチームで共有しやすい設計になっています。リポジトリにコミットすれば、すべての開発者が同じエージェントセーフティネットを利用できます。
+
+---
+
+## 設定スコープ
+
+設定スコープは優先順位の高い順に 3 つあります。
+
+| スコープ | ファイルパス | 用途 |
+|-------|-----------|---------|
+| **project** | `.failproofai/policies-config.json` | リポジトリ単位の設定、バージョン管理にコミット |
+| **local** | `.failproofai/policies-config.local.json` | 個人用のリポジトリ単位オーバーライド、gitignore 対象 |
+| **global** | `~/.failproofai/policies-config.json` | 全プロジェクト共通のユーザーレベルデフォルト |
+
+failproofai がフックイベントを受け取ると、現在の作業ディレクトリに存在する 3 つのファイルをすべて読み込んでマージします。
+
+### マージルール
+
+**`enabledPolicies`** - 3 つのスコープすべての和集合。いずれかのレベルで有効化されたポリシーはアクティブになります。
+
+```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](/ja/built-in-policies) を参照してください。
+
+`enabledPolicies` に含まれていないポリシーは、`policyParams` にエントリがあっても非アクティブになります。
+
+### `policyParams`
+
+型: `Record<string, Record<string, unknown>>`
+
+ポリシーごとのパラメーターオーバーライド。外側のキーがポリシー名、内側のキーはポリシー固有の設定です。各ポリシーで利用可能なパラメーターは [Built-in Policies](/ja/built-in-policies) に記載されています。
+
+ポリシーにパラメーターがあっても指定しない場合は、ポリシーの組み込みデフォルト値が使用されます。`policyParams` をまったく設定していないユーザーは、以前のバージョンと同じ動作になります。
+
+ポリシーのパラメーターブロック内の未知のキーは、フック発火時には無視されますが、`failproofai policies` 実行時に警告として表示されます。
+
+#### `hint`（共通設定）
+
+型: `string`（省略可能）
+
+ポリシーが `deny` または `instruct` を返した際に、理由メッセージに追加されるテキスト。ポリシー自体を変更せずに Claude への具体的なガイダンスを提供するために使用します。
+
+組み込みポリシー、カスタムポリシー（`custom/`）、プロジェクト規約（`.failproofai-project/`）、ユーザー規約（`.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."
+    }
+  }
+}
+```
+
+`block-force-push` が deny した場合、Claude には次のように表示されます: *"Force-pushing is blocked. Try creating a fresh branch instead."*
+
+文字列以外の値および空文字列は無視されます。`hint` が設定されていない場合は動作に変化はありません（後方互換性あり）。
+
+### `customPoliciesPath`
+
+型: `string`（絶対パス）
+
+カスタムフックポリシーを含む JavaScript ファイルへのパス。`failproofai policies --install --custom <path>` によって自動的に設定されます（パスは保存前に絶対パスに解決されます）。
+
+このファイルはフックイベントのたびに新たに読み込まれます。キャッシュは使用されません。作成方法の詳細は [Custom Policies](/ja/custom-policies) を参照してください。
+
+### 規約ベースのポリシー（v0.0.2-beta.7 以降）
+
+明示的な `customPoliciesPath` に加えて、failproofai は `.failproofai/policies/` ディレクトリからポリシーファイルを自動的に検出して読み込みます。
+
+| レベル | ディレクトリ | スコープ |
+|-------|-----------|-------|
+| プロジェクト | `.failproofai/policies/` | バージョン管理でチームと共有 |
+| ユーザー | `~/.failproofai/policies/` | 個人用、全プロジェクトに適用 |
+
+**ファイルのマッチング:** `*policies.{js,mjs,ts}` にマッチするファイルのみ読み込まれます（例: `security-policies.mjs`、`workflow-policies.js`）。ディレクトリ内のその他のファイルは無視されます。
+
+**設定不要:** 規約ポリシーは `policies-config.json` へのエントリが不要です。ディレクトリにファイルを配置するだけで、次のフックイベント時に自動的に読み込まれます。
+
+**全量読み込み:** プロジェクトとユーザーの両方の規約ディレクトリがスキャンされます。両レベルのマッチするファイルがすべて読み込まれます（最初のスコープ優先となる `customPoliciesPath` とは異なります）。
+
+詳細と例については [Custom Policies](/ja/custom-policies) を参照してください。
+
+### `llm`
+
+型: `object`（省略可能）
+
+AI 呼び出しを行うポリシー向けの LLM クライアント設定。ほとんどの環境では不要です。
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## CLI からの設定管理
+
+`policies --install` および `policies --uninstall` コマンドは Claude Code の `settings.json`（フックエントリポイント）に書き込みます。一方、`policies-config.json` は直接管理するファイルです。この 2 つは別物です。
+
+- **`settings.json`** - ツール使用のたびに `failproofai --hook <event>` を呼び出すよう Claude Code に指示する
+- **`policies-config.json`** - どのポリシーをどのパラメーターで評価するかを failproofai に指示する
+
+`policies-config.json` はいつでも直接編集できます。変更は再起動不要で、次のフックイベント時に即座に反映されます。
+
+---
+
+## 例: チームデフォルトを含むプロジェクトレベル設定
+
+`.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/ja/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
+```
+
+---
+
+## カスタムポリシーの読み込み方法（2通り）
+
+### 方法1: 規約ベース（推奨、v0.0.2-beta.7+）
+
+`*policies.{js,mjs,ts}` ファイルを `.failproofai/policies/` に置くだけで自動的に読み込まれます。フラグや設定変更は不要です。gitフックと同じ仕組みです。ファイルを置けばそのまま動きます。
+
+```
+# プロジェクトレベル — gitにコミットしてチームと共有
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# ユーザーレベル — 個人用、全プロジェクトに適用
+~/.failproofai/policies/my-policies.mjs
+```
+
+**動作の仕組み:**
+- プロジェクトディレクトリとユーザーディレクトリの両方がスキャンされます（どちらか一方ではなく、両方が適用されます）
+- 各ディレクトリ内ではファイルがアルファベット順に読み込まれます。順序を制御するには `01-`、`02-` などのプレフィックスを付けてください
+- `*policies.{js,mjs,ts}` に一致するファイルのみ読み込まれ、それ以外のファイルは無視されます
+- 各ファイルは独立して読み込まれます（ファイル単位でフェイルオープン）
+- 明示的な `--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)` — メッセージは `"Blocked by failproofai:"` というプレフィックス付きでClaudeに表示されます。一つの `deny` が発生すると、以降の評価はすべてスキップされます。
+
+`instruct(message)` — メッセージは現在のツール呼び出しに対するClaudeのコンテキストに追記されます。すべての `instruct` メッセージは蓄積されてまとめて配信されます。
+
+<Tip>
+`policyParams` の `hint` フィールドを追加することで、`deny` や `instruct` のメッセージに追加のガイダンスを付け加えられます。コードの変更は不要です。これはカスタム（`custom/`）、プロジェクト規約（`.failproofai-project/`）、ユーザー規約（`.failproofai-user/`）ポリシーでも機能します。詳細は [設定 → hint](/ja/configuration#hint-cross-cutting) を参照してください。
+</Tip>
+
+### 情報提供用のallowメッセージ（ベータ版）
+
+<Note>
+`allow(message)` はv0.0.2-beta.3から利用できるベータ機能です。APIは将来のリリースで変更される可能性があります。それ以前のバージョンでは引数なしの `allow()` のみサポートされています。
+</Note>
+
+`allow(message)` は操作を許可し**つつ**、情報提供のメッセージをClaudeに送信します。メッセージはフックハンドラーのstdoutレスポンスの `additionalContext` として配信されます。これは `instruct` と同じ仕組みですが、意味的に異なります。警告ではなくステータスの更新として扱われます。
+
+| 関数 | 効果 | 使用場面 |
+|----------|--------|----------|
+| `allow(message)` | 許可してClaudeにコンテキストを送信する | チェックが通ったことを確認する、またはチェックがスキップされた理由を説明する場合 |
+
+ユースケース:
+- **ステータス確認:** `allow("All CI checks passed.")` — すべて正常であることをClaudeに伝える
+- **フェイルオープンの説明:** `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.");
+
+    // ... ブランチのステータスを確認 ...
+    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がツールを実行する前 | ツールの入力（例: Bashの場合 `{ command: "..." }`） |
+| `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パスに書き換え、ESM互換性を確保するために一時的な `.mjs` ファイルを作成することで実装されています。
+
+---
+
+## イベントタイプのフィルタリング
+
+`match.events` を使ってポリシーが発火するタイミングを制限できます:
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // セッション終了時にのみ発火する
+    // ctx.session.transcriptPath にセッションの完全なログが含まれる
+    return allow();
+  },
+});
+```
+
+`match` を完全に省略すると、すべてのイベントタイプで発火します。
+
+---
+
+## エラーハンドリングと失敗モード
+
+カスタムポリシーは**フェイルオープン**です。エラーが発生しても組み込みポリシーをブロックしたり、フックハンドラーをクラッシュさせたりすることはありません。
+
+| 失敗 | 動作 |
+|---------|----------|
+| `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` | エージェントのよくある失敗モードをカバーする5つのスターターポリシー |
+| `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/
+```
+
+インストールコマンドは不要です。次のフックイベント時に自動的にファイルが読み込まれます。