failproofai 0.0.2 → 0.0.3

package/.next/standalone/docs/ko/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/ko/cli/remove-policies.mdx

@@ -0,0 +1,44 @@
+---
+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` 초기화 |
+| `--beta` | 설정에서 베타 정책만 제거 |
+
+## 동작 방식
+
+- **정책 이름 미지정** - 설정 파일에서 모든 failproofai 훅 항목을 제거합니다
+- **특정 이름 지정** - 해당 정책을 비활성화하지만 훅은 설치된 상태로 유지됩니다
+
+## 예시
+
+```bash
+# 전역에서 모든 훅 제거
+failproofai policies --uninstall
+
+# 특정 정책 비활성화 (훅은 설치 상태 유지)
+failproofai policies --uninstall block-sudo
+
+# 모든 범위에서 훅 제거
+failproofai policies --uninstall --scope all
+
+# 커스텀 정책 경로 초기화
+failproofai policies --uninstall --custom
+```

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

@@ -0,0 +1,12 @@
+---
+title: 버전 확인
+description: "설치된 failproofai 버전 출력"
+---
+
+```bash
+failproofai --version
+# or
+failproofai -v
+```
+
+설치된 버전 번호를 출력합니다.

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

@@ -0,0 +1,222 @@
+---
+title: 설정
+description: "설정 파일 형식, 세 가지 범위 시스템, 그리고 병합 규칙"
+icon: gear
+---
+
+failproofai는 JSON 설정 파일을 사용하여 어떤 정책이 활성화되어 있는지, 정책이 어떻게 동작하는지, 커스텀 정책을 어디서 로드할지를 제어합니다. 설정은 팀과 쉽게 공유할 수 있도록 설계되었습니다. 저장소에 커밋하면 모든 개발자가 동일한 에이전트 안전망을 갖게 됩니다.
+
+---
+
+## 설정 범위
+
+설정 범위는 세 가지이며, 우선순위 순서대로 평가됩니다:
+
+| 범위 | 파일 경로 | 용도 |
+|-------|-----------|---------|
+| **project** | `.failproofai/policies-config.json` | 저장소별 설정, 버전 관리에 커밋 |
+| **local** | `.failproofai/policies-config.local.json` | 개인 저장소별 오버라이드, gitignore 처리 |
+| **global** | `~/.failproofai/policies-config.json` | 모든 프로젝트에 적용되는 사용자 수준 기본값 |
+
+failproofai가 훅 이벤트를 수신하면, 현재 작업 디렉터리에 존재하는 세 파일을 모두 로드하여 병합합니다.
+
+### 병합 규칙
+
+**`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`가 표시하는 정책 식별자와 정확히 일치해야 합니다. 전체 목록은 [기본 제공 정책](/ko/built-in-policies)을 참조하세요.
+
+`enabledPolicies`에 포함되지 않은 정책은 `policyParams`에 항목이 있더라도 비활성 상태입니다.
+
+### `policyParams`
+
+타입: `Record<string, Record<string, unknown>>`
+
+정책별 파라미터 오버라이드입니다. 외부 키는 정책 이름이고, 내부 키는 정책별로 다릅니다. 각 정책의 사용 가능한 파라미터는 [기본 제공 정책](/ko/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`가 거부할 때, Claude는 다음을 보게 됩니다: *"Force-pushing is blocked. Try creating a fresh branch instead."*
+
+문자열이 아닌 값과 빈 문자열은 조용히 무시됩니다. `hint`를 설정하지 않으면 동작이 변경되지 않습니다(하위 호환성 유지).
+
+### `customPoliciesPath`
+
+타입: `string` (절대 경로)
+
+커스텀 훅 정책이 담긴 JavaScript 파일 경로입니다. `failproofai policies --install --custom <path>` 명령으로 자동 설정되며, 저장 전에 절대 경로로 변환됩니다.
+
+파일은 매 훅 이벤트마다 새로 로드됩니다. 캐싱은 없습니다. 작성 방법은 [커스텀 정책](/ko/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`는 첫 번째 범위가 우선하는 것과 다릅니다).
+
+자세한 내용과 예시는 [커스텀 정책](/ko/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`은 직접 관리하는 파일입니다. 두 파일은 별개입니다:
+
+- **`settings.json`** - 각 도구 사용 시 Claude Code가 `failproofai --hook <event>`를 호출하도록 지시
+- **`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/ko/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 이상)
+
+`.failproofai/policies/` 디렉터리에 `*policies.{js,mjs,ts}` 파일을 넣으면 자동으로 불러옵니다 — 별도의 플래그나 설정 변경이 필요 없습니다. git 훅처럼 파일을 넣으면 바로 작동합니다.
+
+```
+# 프로젝트 레벨 — 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
+
+### Import
+
+```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/`) 정책 모두에서 작동합니다. 자세한 내용은 [Configuration → hint](/ko/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에게 알림
+- **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가 도구를 실행하기 전 | 도구의 입력 (예: 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>
+
+---
+
+## 전이적 import
+
+커스텀 정책 파일은 상대 경로를 사용해 로컬 모듈을 import할 수 있습니다:
+
+```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");
+  },
+});
+```
+
+엔트리 파일에서 도달 가능한 모든 상대 import가 처리됩니다. 이는 `from "failproofai"` import를 실제 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`를 완전히 생략하면 모든 이벤트 유형에서 발동됩니다.
+
+---
+
+## 오류 처리 및 실패 모드
+
+커스텀 정책은 **fail-open** 방식입니다: 오류가 발생해도 내장 정책을 차단하거나 훅 핸들러를 중단시키지 않습니다.
+
+| 실패 상황 | 동작 |
+|---------|----------|
+| `customPoliciesPath` 미설정 | 명시적 커스텀 정책이 실행되지 않음; 컨벤션 정책과 내장 정책은 정상 계속 |
+| 파일을 찾을 수 없음 | `~/.failproofai/hook.log`에 경고 기록; 내장 정책은 계속 |
+| 구문/import 오류 (명시적) | `~/.failproofai/hook.log`에 오류 기록; 명시적 커스텀 정책 건너뜀 |
+| 구문/import 오류 (컨벤션) | 오류 기록; 해당 파일 건너뜀, 다른 컨벤션 파일은 계속 로드 |
+| `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` | 고급 패턴: 전이적 import, 비동기 호출, 출력 스크러빙, 세션 종료 훅 |
+| `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/
+```
+
+설치 명령이 필요하지 않습니다 — 다음 훅 이벤트 시 파일이 자동으로 인식됩니다.