failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/tr/configuration.mdx

@@ -0,0 +1,268 @@
+---
+---
+title: Konfigürasyon
+description: "Konfigürasyon dosyası formatı, üç kapsamlı sistem ve birleştirme kuralları"
+icon: gear
+---
+
+failproofai, hangi politikaların aktif olduğunu, nasıl davrandıklarını ve özel politikaların nereden yükleneceğini kontrol etmek için JSON konfigürasyon dosyalarını kullanır. Konfigürasyon, takımınızla paylaşmak için tasarlanmıştır - bunu deponuza gönderin ve her geliştirici aynı aracı güvenlik ağını alır.
+
+---
+
+## Konfigürasyon kapsamları
+
+Üç konfigürasyon kapsamı vardır ve öncelik sırasına göre değerlendirilir:
+
+| Kapsam | Dosya yolu | Amaç |
+|-------|-----------|---------|
+| **project** | `.failproofai/policies-config.json` | Depo başına ayarlar, sürüm denetimine kaydedilir |
+| **local** | `.failproofai/policies-config.local.json` | Kişisel depo başına geçersiz kılmalar, gitignored |
+| **global** | `~/.failproofai/policies-config.json` | Tüm projeler arasında kullanıcı düzeyinde varsayılanlar |
+
+failproofai bir kanca olayı aldığında, geçerli çalışma dizini için var olan üç dosyayı yükler ve birleştirir.
+
+### Birleştirme kuralları
+
+**`enabledPolicies`** - üç kapsamın tümünün birleşimi. Herhangi bir düzeyde etkinleştirilen bir politika aktiftir.
+
+```text
+project:  ["block-sudo"]
+local:    ["block-rm-rf"]
+global:   ["block-sudo", "sanitize-api-keys"]
+
+resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← tekilleştirilmiş birleşim
+```
+
+**`policyParams`** - belirli bir politika için parametreleri tanımlayan ilk kapsam tamamen kazanır. Bir politikanın parametreleri içinde derin birleştirme yoktur.
+
+```text
+project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← project kazanır, global yoksayılır
+```
+
+```text
+project:  (block-sudo girdisi yok)
+local:    (block-sudo girdisi yok)
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← global'e düşer
+```
+
+**`customPoliciesPaths` / `customPoliciesPath`** - her iki formu tanımlayan ilk kapsam kazanır.
+
+**`disabledCustomPolicies`** - tüm kapsamlar arasında birleşim. Pano, bir bireysel politikayı açık veya kural politikası dosyasından kapatırken burada kaynakla nitelendirilen bir kimlik yazar. Listelenmemiş politikalar varsayılan olarak etkindir; kimlikler kaynak dosyasını içerir, böylece birden fazla dosyada aynı adlı politikalar bağımsız olarak kontrol edilebilir.
+
+**`llm`** - tanımlayan ilk kapsam kazanır.
+
+---
+
+## Konfigürasyon dosyası formatı
+
+```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"
+}
+```
+
+---
+
+## Alan referansı
+
+### `enabledPolicies`
+
+Tür: `string[]`
+
+Etkinleştirilecek politika adlarının listesi. Adlar, `failproofai policies` tarafından gösterilen politika tanımlayıcılarına tam olarak eşleşmelidir. Tam liste için [Yerleşik Politikalar](/tr/built-in-policies) sayfasına bakın.
+
+`enabledPolicies` içinde olmayan politikalar, `policyParams` içinde girdileri olsa bile, etkin değildir.
+
+### `policyParams`
+
+Tür: `Record<string, Record<string, unknown>>`
+
+Politika başına parametre geçersiz kılmaları. Dış anahtar politika adıdır; iç anahtarlar politikaya özeldir. Her politika, [Yerleşik Politikalar](/tr/built-in-policies) sayfasında mevcut parametrelerini belgeler.
+
+Bir politikanın parametreleri varsa ancak bunları belirtmezseniz, politikanın yerleşik varsayılanları kullanılır. `policyParams` yapılandırmayan kullanıcılar, önceki sürümlerle özdeş davranış alırlar.
+
+Bir politikanın parametreler bloğu içindeki bilinmeyen anahtarlar, kanca ateşlemesi sırasında sessizce yoksayılır, ancak `failproofai policies` komutunu çalıştırdığınızda uyarı olarak işaretlenir.
+
+#### `hint` (kesişen alan)
+
+Tür: `string` (isteğe bağlı)
+
+Bir politika `deny` veya `instruct` döndürdüğünde nedene eklenen bir ileti. Politikanın kendisini değiştirmeden Claude'a işlem yapılabilir rehberlik vermek için kullanın.
+
+Herhangi bir politika türüyle çalışır — yerleşik, özel (`custom/`), proje kuralı (`.failproofai-project/`) veya kullanıcı kuralı (`.failproofai-user/`).
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Bunun yerine yeni bir dal oluşturmayı deneyin."
+    },
+    "block-sudo": {
+      "allowPatterns": ["sudo apt-get"],
+      "hint": "sudo olmadan doğrudan apt-get kullanın."
+    },
+    "custom/my-policy": {
+      "hint": "İlk olarak kullanıcıdan onay isteyin."
+    }
+  }
+}
+```
+
+`block-force-push` reddettiğinde, Claude şunu görür: *"Force-push engellenmiştir. Bunun yerine yeni bir dal oluşturmayı deneyin."*
+
+Dize olmayan değerler ve boş dizeler sessizce yoksayılır. `hint` ayarlanmamışsa, davranış değişmez (geriye doğru uyumlu).
+
+### `customPoliciesPath`
+
+Tür: `string` (mutlak yol)
+
+Özel kanca politikaları içeren bir JavaScript dosyasının yolu. Bu, `failproofai policies --install --custom <path>` tarafından otomatik olarak ayarlanır (yol depolanmadan önce mutlak olarak çözümlenir).
+
+Dosya her kanca olayında taze yüklenir - önbelleğe alma yoktur. Yazarlık ayrıntıları için [Özel Politikalar](/tr/custom-policies) sayfasına bakın.
+
+### Kural tabanlı politikalar
+
+Açık `customPoliciesPath` ek olarak, failproofai `.failproofai/policies/` dizinlerinden politika dosyalarını otomatik olarak keşfeder ve yükler:
+
+| Düzey | Dizin | Kapsam |
+|-------|-----------|-------|
+| Proje | `.failproofai/policies/` | Sürüm denetimi yoluyla takımla paylaşılır |
+| Kullanıcı | `~/.failproofai/policies/custom-policies/` | Kişisel, tüm projeler için geçerlidir |
+
+<Note>
+  Kullanıcı düzeyinde dizin, ev dizini yeniden organizasyonunda bir seviye aşağı taşındı. 
+  Eski `~/.failproofai/policies/` yolunda bırakılan dosyalar, yükseltmeden sonra herhangi bir `failproofai` 
+  komutunu çalıştırdığınızda `custom-policies/` içine otomatik olarak taşınır ve komut hangi dosyaları 
+  taşıdığını söyler.
+</Note>
+
+**Dosya eşleştirmesi:** Yalnızca `*policies.{js,mjs,ts}` ile eşleşen dosyalar yüklenir (örn. `security-policies.mjs`, `workflow-policies.js`). Dizindeki diğer dosyalar yoksayılır.
+
+**Konfigürasyon gerekmez:** Kural politikaları `policies-config.json` içinde girdiler gerektirmez. Dosyaları dizine bırakın ve sonraki kanca olayında alınırlar.
+
+**Birleşim yüklemesi:** Hem proje hem de kullanıcı kural dizinleri taranır. Her iki düzeyden tüm eşleşen dosyalar yüklenir (`customPoliciesPath` ilk-kapsam-kazanır kullanan aksine).
+
+Daha fazla ayrıntı ve örnekler için [Özel Politikalar](/tr/custom-policies) sayfasına bakın.
+
+### `llm`
+
+Tür: `object` (isteğe bağlı)
+
+AI çağrıları yapan politikalar için LLM istemci konfigürasyonu. Çoğu kurulum için gerekli değildir.
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## CLI'den konfigürasyonu yönetme
+
+`policies --install` ve `policies --uninstall` komutları aracı CLI'nizin kanca ayarları dosyasına yazarken (kanca giriş noktaları), `policies-config.json` doğrudan yönettiğiniz dosyadır. İkisi ayrıdır:
+
+- **Aracı CLI ayarları** — aracıya her araç kullanımında `failproofai --hook <event>` çağırmasını söyler:
+  - **Claude Code**: `~/.claude/settings.json` (kullanıcı), `<cwd>/.claude/settings.json` (proje), `<cwd>/.claude/settings.local.json` (yerel)
+  - **OpenAI Codex**: `~/.codex/hooks.json` (kullanıcı), `<cwd>/.codex/hooks.json` (proje) — Codex yerel kapsama sahip değildir
+  - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (kullanıcı), `<cwd>/.github/hooks/failproofai.json` (proje) — Copilot yerel kapsama sahip değildir. Kanca girdileri Copilot'un OS tarafından anahtarlanan `bash`/`powershell` komut alanlarını `timeoutSec` ile kullanır; dosya üst düzey `version: 1` işaretleyicisini taşır. Copilot CLI desteği, halk belgeleri belirtmeyen `events.jsonl` kayıt şemasını (pano) daha gerçek dünya oturumlarına karşı doğrularken **beta**'dır. **VS Code Copilot Chat aracı modu (Önizleme)**, `.github/hooks/*.json`, `~/.copilot/hooks/*.json` ve `~/.claude/settings.json` (tarafından yönetilen `chat.hookFilesLocations` ayarı tarafından) kanca yapılandırmalarını aynı Claude şekilli `{hookSpecificOutput:{permissionDecision:"deny",…}}` sözleşmesini kullanarak okur — tam olarak bu `copilot` entegrasyonunun ve `claude` entegrasyonunun (`~/.claude/settings.json`) yazması gereken yollar, bu nedenle `failproofai policies --install --cli copilot` (veya `--cli claude`) **VS Code aracı modunda zaten uygular** ayrı `vscode` entegrasyonu gerekmeden (VS Code'un keşif günlüklerinden canlı olarak onaylandı).
+  - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (kullanıcı), `<cwd>/.cursor/hooks.json` (proje) — Cursor yerel kapsama sahip değildir. Kanca girdileri Claude şekilli `{type, command, timeout}` formunu kullanır (`bash`/`powershell` bölünümü yoktur), ancak Cursor'un [kancalar şemasına](https://cursor.com/docs/hooks) göre düz bir dizi başına camelCase olay anahtarları (`preToolUse`, `beforeSubmitPrompt`, …) altında saklanır; dosya üst düzey `version: 1` işaretleyicisini taşır. İşleyici camelCase → PascalCase'i `CURSOR_EVENT_MAP` aracılığıyla normalleştirir; bu nedenle mevcut yerleşik politikalar değişmeden ateşlenir. Cursor Agent desteği, Cursor'un disk üzerindeki transkript formatını (halk belgelerde belirtilmeyen) daha gerçek dünya yüklemelerine karşı doğrularken **beta**'dır.
+  - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (kullanıcı), `<cwd>/.opencode/opencode.json` + `<cwd>/.opencode/plugins/failproofai.mjs` (proje) — OpenCode yerel kapsama sahip değildir. Diğer beş CLI'den farklı olarak, OpenCode **harici komut kanca sistemi yok**: `plugin: []` dizisine açıkça kayıtlı olan işlem içi JS/TS eklentileri yükler `opencode.json` içinde (`.opencode/plugins/` otomatik keşfi eklentilerin opencode v1.14.33'te nasıl yükleneceği **değildir**). Yükleme, failproofai ikili dosyasını alt işlem çağıran ve ikili dosyanın Claude şekilli JSON yanıtını eklenti semantiğine çeviren küçük bir oluşturulan eklenti parçası bırakır: araç olayı reddi için `throw new Error()` (araç çağrısını iptal eder), `client.session.prompt(...)` `instruct` ve sıra sonu `Stop` / `SubagentStop` reddi için (`session.idle` bildir yapısı olduğu ve bundan atma yapısı bir işlemi için — `instruct` için (reddi nedeni bir sonraki kullanıcı iletisi olarak gönderilir — tek zorla yeniden deneme kanalı) ve izin vermeyi allow için no-op (`OPENCODE_TOOL_INPUT_MAP` aracılığıyla `filePath` → `file_path`, `oldString` → `old_string` gibi) normalleştirir, böylece `block-read-outside-cwd`, `block-env-files` ve `block-secrets-write` gibi yol denetimi yerleşik öğeleri OpenCode araç çağrılarında değişmeden ateşlenir. Oturumlar opencode'un SQLite DB'sinde `~/.local/share/opencode/opencode.db` adında yaşar; panonun oturum görüntüleyeni bunları `opencode db --format json` ve `opencode export <id>` aracılığıyla okur. OpenCode desteği davranış sürümler arasında ve daha gerçek dünya oturumlarına karşı doğrulanırken **beta**'dır. [OpenCode eklentileri belgelerine](https://opencode.ai/docs/plugins/) bakın.
+  - **Pi _(beta)_**: `~/.pi/agent/settings.json` (kullanıcı), `<cwd>/.pi/settings.json` (proje) — Pi yerel kapsama sahip değildir. Pi başlangıçta TypeScript uzantı paketlerini yükler; ayarlar dosyası düz bir dize dizisidir `{"packages": ["./relative/path", …]}`. failproofai, paketlenen `pi-extension/` dizinine işaret eden tek bir paketler-dizisi girdisi yazar. Uzantı dahili olarak Pi'nin `tool_call` / `user_bash` / `input` / `session_start` olaylarına abone olur ve `failproofai --hook <Event> --cli pi` öğesine çıkar; işleyici alt çizgi_alt_snek_kasa → PascalCase'i `PI_EVENT_MAP` aracılığıyla normalleştirir, böylece mevcut yerleşik politikalar değişmeden ateşlenir. Araç giriş argümanları da `PI_TOOL_INPUT_MAP` aracılığıyla normalleştirilir (Pi'nin Read / Write / Edit, `file_path` yerine `path` teslim eder; üst düzey anahtarı eşlemek `block-env-files` ve `block-secrets-write` ateşlemesine izin verir — `block-read-outside-cwd` zaten bir `path` geri dönüşüne sahipti). Pi desteği Pi'nin uzantı API'si ve oturum günlüğü düzeni stabilize olurken **beta**'dır.
+  - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**yalnızca kullanıcı kapsamı** — Hermes proje/yerel yapılandırmaya sahip değildir). Hermes bir Slack/Telegram **ağ geçidi**dir, bu nedenle bir yükleme her platformdan (Slack/Telegram/cli/cron) araç çağrılarını **ve** iç alt aracıları keser. Kanca girdileri, Hermes'in snek_kasa olayları (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`) tarafından anahtarlanan `hooks:` haritası altında bir `{command, timeout}` çiftidir; işleyici olayları `HERMES_EVENT_MAP` aracılığıyla ve araç adlarını `HERMES_TOOL_MAP` aracılığıyla normalleştirir, böylece yerleşik politikalar değişmeden ateşlenir. Yapılandırma, yorum koruyan bir YAML `Document` gidiş dönüş yapılarak düzenlenir, bu nedenle operatörün diğer ayarları kalır ve yükleme `hooks_auto_accept: true` ayarlar, böylece başsız ağ geçidi (TTY yok) kancaları izin istemi olmadan çalıştırır. Değerlendirici Hermes'in `{"decision":"block","reason"}` stdout sözleşmesini yayar (Hermes çıkış kodlarını yoksayar). **Sınırlamalar:** Hermes sıra sonu `Stop` olayına sahip değildir, bu nedenle `require-*-before-stop` yerleşik öğeleri hiçbir zaman onun için ateşlenmez (inapplicable, kırılmış değil); `instruct` günlüğe kaydedilen notla allow öğesine düşer (ek içerik kanalı yoktur); ve çıkış sırrı redaksiyonu (`sanitize-*`) kabuk kanca sözleşmesi üzerinde araç çıkışını yeniden yazamaz. Hermes, çevrimdışı bir **denetim** kaynağıdır — pano oturumlarını doğrudan `~/.hermes/state.db` adresinden okur.
+  - **OpenClaw (openclaw ağ geçidi)**: `~/.openclaw/openclaw.json` (**yalnızca kullanıcı kapsamı** — OpenClaw proje/yerel yapılandırmaya sahip değildir). Hermes gibi, OpenClaw kendi kendine barındırılan çok kanallı bir **ağ geçidi**dir, bu nedenle bir yükleme her kanaldan araç çağrılarını ve iç alt aracılarını keser. Uygulama OpenClaw'un **işlem içi eklenti kancastları** aracılığıyla çalışır (dosya tabanlı iç kancastları yalnızca gözlem amaçlıdır ve engelleyemez), bu nedenle — OpenCode/Pi gibi — failproofai statik bir `openclaw-plugin/` paketi gönderir; bu, failproofai ikili dosyasını eş zamansız olarak çıkarır ve kararı çevirir. Yükleme, gönderilen eklenti dizinini `openclaw.json`'nin `plugins.load.paths[]` içinde kaydeder ve `plugins.entries.failproofai` altında etkinleştirir (`hooks.allowConversationAccess: true` ile, ham konuşma kancastları için gereklidir). Değerlendirici düz bir `{permission, reason}` kararı yayar ve şim bunu her kancanın yerel dönüş şekline eşler: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), ve `before_agent_finalize → {action:"revise", reason}` (**Stop** — gerçek bir sıra sonu kapısı, bu nedenle `require-*-before-stop` yerleşik öğeleri **uygular**, Hermes'in aksine). Olaylar ve araç adları ikili tarafında `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) aracılığıyla normalleştirilir, böylece yerleşik politikalar değişmeden ateşlenir; şim herhangi bir çıkarma/ayrıştırma/zaman aşımı hatasında açık başarısız olur. OpenClaw, çevrimdışı bir **denetim** kaynağıdır — pano JSONL oturumlarını `~/.openclaw/agents/<agentId>/sessions/<uuid>.jsonl` adresinden okur.
+  - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (kullanıcı), `<cwd>/.factory/hooks.json` (proje) — Factory yerel kapsama sahip değildir. droid, Claude stilinde harici komut kanca sistemini gönderir, ancak droid v0.171.0'a karşı canlı olarak doğrulanmış iki tuhaflık vardır: (1) olay adları `hooks.json` **üst düzeyinde** yaşar — **bir `"hooks"` sarıcı yoktur** (droid birini reddeder); araç olayları (`PreToolUse`/`PostToolUse`) `"matcher": "*"` taşır, araç olmayan olaylar bunu atlar. (2) Reddi, kanca **çıkış kodu 2 + stderr** tarafından yapılır, JSON kararı değil — değerlendirici'nin `factory` dalı araç/istem olayları için çıkış 2 ve sıra sonu `Stop` olayında `{decision:"block", reason}` döndürür (droid'in tek zorla yeniden deneme kanalı). Olaylar zaten PascalCase'dir (olay eşlemesi yoktur) ve yük Claude snek_kasa'dır; yalnızca araç adları `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …) aracılığıyla normalleştirilir. Factory, çevrimdışı bir **denetim** kaynağıdır — pano disk üzerindeki JSONL oturumlarını `~/.factory/sessions/<encoded-cwd>/<sessionId>.jsonl` adresinden okur.
+  - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (kullanıcı), `<cwd>/.devin/config.json` (proje) — Devin yerel kapsama sahip değildir. Devin bir **saf Claude klonudur** devin v3000.1.27'ye karşı canlı olarak doğrulanmıştır: standart Claude `"hooks"` sarıcısı şemasını kullanır (yazma işlemleri korunan yollar, bu nedenle yapılandırma dosyasının diğer anahtarları — `org_id`, `theme_mode`, … — kalır), zaten PascalCase olay adları (olay eşlemesi, işleyici dalı yoktur) ve Claude snek_kasa stdin yükü (normalleştirme yoktur). Değerlendirici'nin `devin` dalı **her** olay için çıkış 0'da `{"decision":"block","reason"}` JSON ile reddeder; sıra sonu `Stop` olayında neden, `require-*-before-stop` yerleşik öğelerinin uygulanması için ZORUNLU İŞLEM zorla yeniden deneme ifadesini taşır. Yalnızca araç adları `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` zaten Canonical'dir) aracılığıyla normalleştirilir. Devin, çevrimdışı bir **denetim** kaynağıdır — pano SQLite oturumlarını `~/.local/share/devin/cli/sessions.db` adresinden okur (her `sessions` satırı gerçek bir `working_directory` taşır, bu nedenle oturumlar proje cwd tarafından gruplandırılır; Claude gibi).
+  - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (kullanıcı), `<cwd>/.agents/hooks.json` (proje) — Antigravity yerel kapsama sahip değildir. Factory/Devin'in aksine, Antigravity agy v1.1.2'ye karşı canlı olarak doğrulanan **kendi** sözleşmesine sahiptir. `hooks.json`, **adlandırılmış kanca** şemasını kullanır: üst düzey anahtar bir kanca *adıdır* (`"failproofai"`), değeri olay→işleyiciler haritasıdır — araç olayları (`PreToolUse`/`PostToolUse`) işleyicileri `{matcher:"*", hooks:[…]}` içine sarmalanır, `PreInvocation`/`Stop` **düz** işleyici dizileridir (diğer adlandırılmış kancalar korunur). stdin yükü **camelCase protojson**'dur (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai bunu politikalar çalışmadan önce snek_kasa'ya normalleştirir ve `run_command`'in PascalCase argümanlarını (`CommandLine`/`Cwd`) `ANTIGRAVITY_TOOL_INPUT_MAP` aracılığıyla eşler. Değerlendirici'nin `antigravity` dalı Antigravity'nin **kendi** yanıt şekillerini kullanır: `{decision:"deny", reason}` araç/istemi engeller (çıkış 0), sıra sonu `Stop` olayında `{decision:"continue", reason}` döngüyü yeniden girer (bu nedenle `require-*-before-stop` yerleşik öğeleri uygularlar) ve `{injectSteps:[{ephemeralMessage}]}` `PreInvocation` (→ `UserPromptSubmit`) üzerine bir talimat enjekte eder. Araç adları `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …) aracılığıyla normalleştirilir. Antigravity, çevrimdışı bir **denetim** kaynağıdır — pano düz JSONL transkriptlerini `~/.gemini/antigravity-cli/brain/<conversationId>/.system_generated/logs/transcript_full.jsonl` adresinden okur (konuşma dizini `conversation_summaries.db`'de).
+  - **Goose (kod adı goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (kullanıcı), `<cwd>/.agents/plugins/failproofai/hooks/hooks.json` (proje) — Goose yerel kapsama sahip değildir. Uygulama Goose'un **kancalar** sistemini, çapraz aracı **Açık Eklentiler** spesifikasyonunu kullanır: yükleyici sadece `failproofai` eklenti dizinini bırakır ve Goose başlangıçta onu otomatik keşfeder (bunu `~/.config/goose/config.yaml`'ye kendi kendine kaydeder). `hooks.json`, üst düzey `"hooks"` sarıcı **içeren** Açık Eklentiler şemasını kullanır ve eşleyici **her olay için atlanır** — çıplak `"*"` hiçbir şeyinle eşleşmeyen geçersiz bir regex'tir (goose v1.43.0'ye karşı canlı olarak doğrulanan). Olay adları zaten PascalCase'dir (olay eşlemesi yoktur); stdin yükü `event`/`working_dir` kullanır; işleyici bunu `hook_event_name`/`cwd` için normalleştirir. Değerlendirici'nin `goose` dalı çıkış 0'da `{"decision":"block","reason"}` JSON ile reddeder, **`PreToolUse`** olayında onurlanır (goose ≥ v1.37.0'de gönderilen) — bu, kabuk aracı **ve temsilci seçilen alt aracılar içinde** ateşlenir, bu nedenle tek yeterli reddi noktasıdır; diğer herhangi bir kanca hatası **açık başarısız** olur. Goose, **`Stop` olayına sahip değildir**, bu nedenle `require-*-before-stop` yerleşik öğeleri uygulanmaz (Hermes'te olduğu gibi). Araç adları `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) ve yol anahtarları `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`) aracılığıyla normalleştirilir. Goose, çevrimdışı bir **denetim** kaynağıdır — pano SQLite oturumlarını `~/.local/share/goose/sessions/sessions.db` adresinden okur (her `sessions` satırı gerçek bir `working_dir` taşır, bu nedenle oturumlar proje cwd tarafından gruplandırılır; Devin gibi; `--no-session` karalama çalıştırmaları filtrelenir).
+- **`policies-config.json`** — failproofai'ya hangi politikaları değerlendireceğini ve hangi parametrelerle (tüm aracı CLI'leri arasında paylaşılan) söyler
+
+Belirli bir aracıyı hedeflemek için `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` geçirin (boşlukla ayrılmış veya herhangi bir alt küme için tekrarlanan):
+
+```bash
+failproofai policies --install --cli codex --scope project
+failproofai policies --install --cli copilot --scope project
+failproofai policies --install --cli cursor --scope project
+failproofai policies --install --cli opencode --scope project
+failproofai policies --install --cli pi --scope project
+failproofai policies --install --cli hermes --scope user
+failproofai policies --install --cli openclaw --scope user
+failproofai policies --install --cli factory --scope project
+failproofai policies --install --cli devin --scope project
+failproofai policies --install --cli antigravity --scope project
+failproofai policies --install --cli goose --scope project
+failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose
+```
+
+`--cli` atlandığında, `failproofai` hangi aracı CLI'lerinin kurulu olduğunu algılar (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`):
+
+- **Bir CLI algılandı** — onay istemeksizin o CLI'yi otomatik seçer.
+- **Çok sayıda CLI algılandı** etkileşimli terminalde — `Detected (N)` bölümüne gruplandırılmış ok tuşu tek seçim istemi gösterir (`Install for all N detected` toplam satırı + her algılanan CLI ayrı ayrı) ve `Not installed (M) · install hooks ahead of time` bölümü her desteklenen CLI'yi ileriye dönük yükleme seçeneği olarak listeler (↑↓ taşı, Enter seç, ^C çık). Kaldırma akışı yalnızca Algılanan bölümü gösterir.
+- **Çok sayıda CLI algılandı** etkileşimsiz çalıştırmada (CI, TTY yoktur) — onay istemeksizin tüm algılanan CLI'ler için yüklenir.
+- **Hiç algılanmadı** — `claude` olarak geri döner ve PATH'de aracı ikili bulunmadığını uyarır; kanca komutu yine yazılır, bu nedenle bir tanesi yükler yüklenmez etkinleşir.
+
+`policies-config.json` öğesini dilediğiniz zaman doğrudan düzenleyebilir; değişiklikler yeniden başlama gerekmeksizin sonraki kanca olayında etkili olur.
+
+---
+
+## Örnek: takım varsayılanları olan proje düzeyinde konfigürasyon
+
+`.failproofai/policies-config.json` öğesini deponuza gönderin:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "block-env-files"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "hotfix"]
+    }
+  }
+}
+```
+
+Her geliştirici daha sonra `.failproofai/policies-config.local.json` (gitignored) oluşturabilir; takım arkadaşlarını etkilemeden kişisel geçersiz kılmalar için.

package/.next/standalone/docs-old/tr/custom-policies.mdx

@@ -0,0 +1,358 @@
+---
+title: Özel İlkeler
+description: "JavaScript'te kendi ilkelerinizi yazın - kuralları uygulayın, kaymaları önleyin, başarısızlıkları algılayın, dış sistemlerle entegre olun"
+icon: code
+---
+
+Özel ilkeler, herhangi bir aracı davranışı için kurallar yazmanıza izin verir: proje kurallarını uygulayın, kaymaları önleyin, yıkıcı işlemleri engelleyin, takılı kalan aracıları algılayın veya Slack, onay iş akışları ve daha fazlasıyla entegre olun. Yerleşik ilkelerle aynı kanca olay sistemini ve `allow`, `deny`, `instruct` kararlarını kullanırlar.
+
+---
+
+## Hızlı örnek
+
+```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();
+  },
+});
+```
+
+Yükleyin:
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## Özel ilkeleri yüklemenin iki yolu
+
+### Seçenek 1: Kurala dayalı (önerilen)
+
+`*policies.{js,mjs,ts}` dosyalarını `.failproofai/policies/` içine bırakın ve otomatik olarak yüklenir — bayrak veya yapılandırma değişikliğine gerek yok. Bu git kancaları gibi çalışır: bir dosya bırakın, işi görür.
+
+```
+# Proje düzeyi — git'e kaydedildi, takımla paylaşıldı
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# Kullanıcı düzeyi — kişisel, tüm projeler için uygulanır
+~/.failproofai/policies/my-policies.mjs
+```
+
+**Nasıl çalışır:**
+- Hem proje hem de kullanıcı dizinleri taranır (birleşim — birinci kapsamı kazanır değil)
+- Dosyalar her dizin içinde alfabetik olarak yüklenir. Sırayı kontrol etmek için `01-`, `02-` ile önek atın
+- Yalnızca `*policies.{js,mjs,ts}` ile eşleşen dosyalar yüklenir; diğer dosyalar yok sayılır
+- Her dosya bağımsız olarak yüklenir (dosya başına başarısız açık)
+- Açık `--custom` ve yerleşik ilkelerle birlikte çalışır
+
+<Tip>
+Kurala dayalı ilkeler, kuruluşunuz için bir kalite standardı oluşturmanın en kolay yoludur. `.failproofai/policies/` öğesini git'e kaydedin ve her takım üyesi otomatik olarak aynı kuralları alır — geliştirici başına kuruluma gerek yok. Takımınız yeni başarısızlık modlarını keşfettikçe, bir ilke ekleyin ve gönderin. Zamanla bunlar, her katkı ile iyileşmeye devam eden, canlı bir kalite standardı haline gelir.
+</Tip>
+
+### Seçenek 2: Açık dosya yolu
+
+```bash
+# Özel ilkeler dosyasıyla yükleyin
+failproofai policies --install --custom ./my-policies.js
+
+# Özel ilke yollarını değiştirin
+failproofai policies --install --custom ./new-policies.js
+
+# Birden fazla açık dosyayı yapılandırın (bayrağa göre sırada yüklenir)
+failproofai policies --install --custom ./security.js --custom ./workflow.js
+
+# Yapılandırmadaki tüm açık özel ilke yollarını kaldırın
+failproofai policies --uninstall --custom
+```
+
+Çözümlenen mutlak yollar `policies-config.json` dosyasında `customPoliciesPaths` olarak depolanır. Birden fazla dosyayı yapılandırmak için `--custom` öğesini yineleyin. Eski `customPoliciesPath` alanını kullanan mevcut yapılandırmalar çalışmaya devam eder. Dosyalar her kanca olayında yeni yüklenir — olaylar arasında önbelleğe alma yoktur.
+
+Her kayıtlı ilke, panodan kendi geçişiyle görünür. Bir ilkeyi kapatmak, kaynaktan nitelendirilmiş kimliğini `disabledCustomPolicies` içinde kaydeder; dosya ve diğer ilkeleri yüklenmeye devam eder, devre dışı bırakılan ilke olay eşleştirmesinden önce hariç tutulur. Dosyalar arasında yinelenen ilke adlarının bağımsız geçişleri vardır.
+
+### Her ikisini birlikte kullanma
+
+Kurala dayalı ilkeler ve açık `--custom` dosyaları birlikte olabilir. Yükleme sırası:
+
+1. Açık `customPoliciesPaths` dosyaları (yapılandırılan sırada)
+2. Proje kurala dayalı dosyaları (`{cwd}/.failproofai/policies/`, alfabetik)
+3. Kullanıcı kurala dayalı dosyaları (`~/.failproofai/policies/`, alfabetik)
+
+---
+
+## API
+
+### İçe aktarma
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+Bir ilkeyi kaydeder. Aynı dosyada birden fazla ilke için gerektiği kadar çağırın.
+
+```ts
+customPolicies.add({
+  name: string;                         // gerekli - benzersiz tanımlayıcı
+  description?: string;                 // `failproofai policies` çıktısında gösterilir
+  match?: { events?: HookEventType[] }; // olay türüne göre filtreleyin; hepsine eşleştirmek için atla
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### Karar yardımcıları
+
+| İşlev | Etki | Ne zaman kullanılır |
+|----------|--------|----------|
+| `allow()` | İşleme sessizce izin ver | İşlem güvenli, mesaja gerek yok |
+| `deny(message)` | İşlemi engelle | Aracı bu işlemi gerçekleştirmemelidir |
+| `instruct(message)` | Engellememeden bağlam ekle | Aracıya yolunda kalması için ek bağlam ver |
+
+`deny(message)` - mesaj Claude'a `"Blocked by failproofai:"` ön ekiyle görünür. Tek bir `deny` tüm sonraki değerlendirmeleri kısa devre yapar.
+
+`instruct(message)` - mesaj mevcut araç çağrısı için Claude'un bağlamına eklenir. Tüm `instruct` mesajları biriktirilir ve birlikte iletilir.
+
+<Tip>
+`policyParams` içine bir `hint` alanı ekleyerek herhangi bir `deny` veya `instruct` mesajına ekstra rehberlik ekleyebilirsiniz — kod değişikliğine gerek yok. Bu, özel (`custom/`), proje kurala dayalı (`.failproofai-project/`), ve kullanıcı kurala dayalı (`.failproofai-user/`) ilkeleri için de çalışır. Ayrıntılar için [Yapılandırma → hint](/tr/configuration#hint-cross-cutting) bölümüne bakın.
+</Tip>
+
+### Bilgilendirici izin mesajları
+
+`allow(message)` işleme izin verir **ve** Claude'a bir bilgilendirici mesaj geri gönderir. Mesaj, kanca işleyicisinin stdout yanıtında `additionalContext` olarak iletilir — `instruct` tarafından kullanılan aynı mekanizma, ancak anlam olarak farklı: bir uyarı değil, bir durum güncellemesidir.
+
+| İşlev | Etki | Ne zaman kullanılır |
+|----------|--------|----------|
+| `allow(message)` | İzin ver ve Claude'a bağlam gönder | Bir kontrolün geçtiğini onaylayın veya bir kontrolün neden atlandığını açıklayın |
+
+Kullanım durumları:
+- **Durum onayları:** `allow("All CI checks passed.")` — Claude'a her şeyin yeşil olduğunu söyler
+- **Başarısız açık açıklamalar:** `allow("GitHub CLI not installed, skipping CI check.")` — Claude'a tam bağlamı alması için bir kontrolün neden atlandığını söyler
+- **Birden fazla mesaj birikir:** birden fazla ilke her biri `allow(message)` döndürürse, tüm mesajlar yeni satırlarla birleştirilir ve birlikte iletilir
+
+```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.");
+
+    // ... branch durumunu kontrol et ...
+    if (allPushed) {
+      return allow("Branch is up to date with remote.");
+    }
+    return deny("Unpushed changes detected.");
+  },
+});
+```
+
+### `PolicyContext` alanları
+
+| Alan | Tür | Açıklama |
+|-------|------|-------------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string \| undefined` | Çağrılan araç (örn. `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | Aracın giriş parametreleri |
+| `payload` | `Record<string, unknown>` | Claude Code'dan tam ham olay yükü |
+| `session` | `SessionMetadata \| undefined` | Oturum bağlamı (aşağıya bakın) |
+
+### `SessionMetadata` alanları
+
+| Alan | Tür | Açıklama |
+|-------|------|-------------|
+| `sessionId` | `string` | Claude Code oturum tanımlayıcısı |
+| `cwd` | `string` | Claude Code oturumunun çalışma dizini |
+| `transcriptPath` | `string` | Oturumun JSONL transkript dosyasının yolu |
+
+### Olay türleri
+
+| Olay | Ne zaman ateşlenir | `toolInput` içeriği |
+|------|--------------|----------------------|
+| `PreToolUse` | Claude bir araç çalıştırmadan önce | Aracın girdisi (örn. Bash için `{ command: "..." }`) |
+| `PostToolUse` | Bir araç tamamlandıktan sonra | Aracın girdisi + `tool_result` (çıktı) |
+| `Notification` | Claude bir bildirim gönderdiğinde | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - kancaları her zaman `allow()` döndürmelidir, bildirimleri engelleyemezler |
+| `Stop` | Claude oturumu bittiğinde | Boş |
+
+---
+
+## Değerlendirme sırası
+
+İlkeler şu sırada değerlendirilir:
+
+1. Yerleşik ilkeler (tanım sırasında)
+2. `customPoliciesPath` öğesinden açık özel ilkeler (`.add()` sırasında)
+3. Proje `.failproofai/policies/` öğesinden kurala dayalı ilkeler (dosyalar alfabetik, içinde `.add()` sırası)
+4. Kullanıcı `~/.failproofai/policies/` öğesinden kurala dayalı ilkeler (dosyalar alfabetik, içinde `.add()` sırası)
+
+<Note>
+İlk `deny` tüm sonraki ilkeleri kısa devre yapar. Tüm `instruct` mesajları biriktirilir ve birlikte iletilir.
+</Note>
+
+---
+
+## Geçişli içe aktarmalar
+
+Özel ilke dosyaları göreli yollar kullanarak yerel modülleri içe aktarabilir:
+
+```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");
+  },
+});
+```
+
+Giriş dosyasından ulaşılabilecek tüm göreli içe aktarmalar çözülür. Bu, `from "failproofai"` içe aktarmalarını gerçek dist yoluna yeniden yazarak ve ESM uyumluluğunu sağlamak için geçici `.mjs` dosyaları oluşturarak uygulanır.
+
+---
+
+## Olay türü filtreleme
+
+Bir ilkenin ne zaman ateşleneceğini sınırlamak için `match.events` öğesini kullanın:
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // Yalnızca oturum sona erdiğinde ateşlenir
+    // ctx.session.transcriptPath tam oturum günlüğünü içerir
+    return allow();
+  },
+});
+```
+
+Her olay türünde ateşlemek için `match` öğesini tamamen atla.
+
+---
+
+## Hata işleme ve başarısızlık modları
+
+Özel ilkeler **başarısız açık** olarak tanımlanır: hatalar yerleşik ilkeleri asla engellemez veya kanca işleyicisini çökertemez.
+
+| Başarısızlık | Davranış |
+|---------|----------|
+| `customPoliciesPath` ayarlanmadı | Açık özel ilkeler çalışmaz; kurala dayalı ilkeler ve yerleşik olanlar normal olarak devam eder |
+| Dosya bulunamadı | Uyarı `~/.failproofai/hook.log` öğesine kaydedilir; yerleşik olanlar devam eder |
+| Sözdizimi/içe aktarma hatası (açık) | Hata `~/.failproofai/hook.log` öğesine kaydedilir; açık özel ilkeler atlanır |
+| Sözdizimi/içe aktarma hatası (kurala dayalı) | Hata kaydedilir; bu dosya atlanır, diğer kurala dayalı dosyalar hala yüklenir |
+| `fn` çalışma zamanında hata atarsa | Hata kaydedilir; bu kanca `allow` olarak işlenir; diğer kancalar devam eder |
+| `fn` 10 saniyeden uzun sürerse | Zaman aşımı kaydedilir; `allow` olarak işlenir |
+| Kurala dayalı dizin eksikse | Kurala dayalı ilkeler çalışmaz; hata yok |
+
+<Tip>
+Özel ilke hatalarını hata ayıklamak için günlük dosyasını izleyin:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## Tam örnek: birden fazla ilke
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// Aracıyı secrets/ dizinine yazmaktan engelle
+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();
+  },
+});
+
+// Aracıyı yolunda tut: taahhüt etmeden önce testleri doğrula
+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();
+  },
+});
+
+// Dondurma döneminde planlanmamış bağımlılık değişikliklerini engelle
+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 };
+```
+
+---
+
+## Örnekler
+
+`examples/` dizini çalıştırmaya hazır ilke dosyalarını içerir:
+
+| Dosya | İçerik |
+|------|----------|
+| `examples/policies-basic.js` | Genel aracı başarısızlık modlarını kapsayan beş başlangıç ilkesi |
+| `examples/policies-advanced/index.js` | İleri desenler: geçişli içe aktarmalar, zaman uyumsuz çağrılar, çıktı temizleme ve oturum sonu kancaları |
+| `examples/convention-policies/security-policies.mjs` | Kurala dayalı güvenlik ilkeleri (.env yazmasını engelle, git geçmişini yeniden yazmasını önle) |
+| `examples/convention-policies/workflow-policies.mjs` | Kurala dayalı iş akışı ilkeleri (test anımsatıcıları, denetim dosyası yazmaları) |
+
+### Açık dosya örneklerini kullanma
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### Kurala dayalı örnekleri kullanma
+
+```bash
+# Proje düzeyine kopyala
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# Veya kullanıcı düzeyine kopyala
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+Yükleme komutu gerekmez — dosyalar bir sonraki kanca olayında otomatik olarak alınır.