failproofai 1.0.1-beta.1 → 1.0.1

package/.next/standalone/docs-old/ar/built-in-policies.mdx

@@ -0,0 +1,860 @@
+---
+---
+title: السياسات المدمجة
+description: "جميع 39 سياسة مدمجة تلتقط أنماط فشل الوكيل الشائعة"
+icon: shield
+---
+
+يأتي failproofai مع 39 سياسة مدمجة تلتقط أنماط فشل الوكيل الشائعة. كل سياسة تُطلق على نوع حدث hook معين واسم أداة معينة. تقبل تسع عشرة سياسة معاملات تتيح لك ضبط سلوكها دون كتابة أي كود. تفرض خمس سياسات سير عمل خط أنابيب commit → push → PR → CI قبل أن يتوقف Claude.
+
+---
+
+## نظرة عامة
+
+تُجمع السياسات في فئات:
+
+| الفئة | السياسات | نوع Hook |
+|----------|----------|-----------|
+| [الأوامر الخطرة](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse |
+| [أوامر البنية التحتية](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse |
+| [الأسرار (المعالجات)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse |
+| [البيئة](#environment) | block-env-files, protect-env-vars | PreToolUse |
+| [الوصول إلى الملفات](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse |
+| [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse |
+| [قاعدة البيانات](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse |
+| [التحذيرات](#warnings) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse |
+| [مديري الحزم](#package-managers) | prefer-package-manager | PreToolUse |
+| [سير العمل](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop |
+
+- **`block-`** — منع الوكيل من المتابعة.
+- **`warn-`** — إعطاء الوكيل سياق إضافي حتى يتمكن من تصحيح نفسه.
+- **`sanitize-`** — حذف البيانات الحساسة من إخراج الأداة قبل أن يراها الوكيل.
+
+### النطاقات
+
+كل سياسة تعيش في فتحة `<namespace>/<name>`. تنتمي السياسات المدمجة إلى
+النطاق **`failproofai/`** — على سبيل المثال، `failproofai/sanitize-jwt`. يمنع
+النطاق التصادمات عند تحميل سياسات مخصصة أو من جهات خارجية
+بأسماء قصيرة متشابهة.
+
+في إعدادك يمكنك الإشارة إلى السياسة المدمجة باستخدام اسمها القصير أو
+اسمها المؤهل؛ كلا النموذجين يحلان نفس السياسة:
+
+```json
+{
+  "enabledPolicies": [
+    "sanitize-jwt",
+    "failproofai/block-rm-rf"
+  ]
+}
+```
+
+إذا لم يكن للاسم علامة `/`، يعاملها failproofai كتابعة للنطاق الافتراضي
+`failproofai`. الأسماء التي تحتوي بالفعل على `/` (مثل `myorg/foo`،
+`custom/my-hook`) تُبقى كما هي.
+- **`require-`** — منع حدث Stop حتى تُستوفى الشروط.
+
+---
+
+<Tip>
+تدعم كل سياسة حقل اختياري `hint` في `policyParams`. يُضاف التلميح إلى رسالة deny أو instruct التي يراها Claude، مما يوفر توجيهات قابلة للتنفيذ دون تعديل كود السياسة. يعمل مع السياسات المدمجة والمخصصة والاتفاقية. انظر [التكوين → hint](/ar/configuration#hint-cross-cutting) للتفاصيل.
+</Tip>
+
+---
+
+## الأوامر الخطرة
+
+منع الوكلاء من تشغيل عمليات يصعب التراجع عنها أو قد تضر النظام المضيف.
+
+### `block-sudo`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يرفض أي أمر `sudo` أو `doas`.
+
+يحجب أمر يشغل ملف تنفيذي للرفع في **موضع الأمر**. المطابقة هيكلية وليست نصية: يُقسم الأمر إلى قطاعات بالطريقة التي تقسمها shell، تُزال تعيينات البادئة (`FOO=bar`)، عمليات إعادة التوجيه، والمنفذات مع أعلامها (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …)، ويُقارن الملف التنفيذي الناتج **بالاسم الأساسي**. إذن `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` و `bash -c "sudo …"` كلها مرفوضة، و `doas` يُعامل كنفس الإمكانية تحت اسم مختلف.
+
+لأنها تستقر على موضع الأمر وليس الكلمة التي تظهر في أي مكان، فهي **لا تُطلق** على الأوامر التي تذكره فقط — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, أو `grep` يحتوي على كلمة بديلة تُشغل عادةً.
+
+<Warning>
+يوقف المحاولة الواضحة؛ لا يغلق الفئة. يمكن للوكيل الذي يستطيع تشغيل shell عشوائية الوصول إلى الرفع بشكل غير مباشر — من خلال متغير (`S=sudo; $S …`)، أنبوب مفكك base64، أو سكريبت wrapper على القرص — لأن فحص سلسلة أمر واحدة لا يمكن أن يتابع تلك. تعامل مع هذا كدرابزين ضد الأخطاء والرفع العرضي، وليس حد أمان ضد وكيل مصمم. يجب أن يُفرض الحد الحقيقي أسفل shell.
+</Warning>
+
+**المعاملات:**
+
+| المعامل | النوع | الافتراضي | الوصف |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | بادئات الأوامر الدقيقة المسموح بها. يُطابق كل إدخال مقابل الرموز المحللة argv. |
+
+**مثال:**
+
+```json
+{
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+    }
+  }
+}
+```
+
+مع هذا الإعداد، `sudo systemctl status nginx` مسموح، لكن `sudo rm /etc/hosts` مرفوض.
+
+<Note>
+تُطابق الأنماط الرموز المحللة، وليس سلسلة الأمر الخام. يمنع هذا التجاوز عبر مشغلات shell المرفقة (مثل `sudo systemctl status x; rm -rf /` لا يطابق `sudo systemctl status *`).
+</Note>
+
+---
+
+### `block-rm-rf`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يرفض `rm -rf`, `rm -fr`، والأشكال الأخرى المشابهة للحذف المتكرر.
+
+**المعاملات:**
+
+| المعامل | النوع | الافتراضي | الوصف |
+|-------|------|---------|-------------|
+| `allowPaths` | `string[]` | `[]` | المسارات الآمنة للحذف المتكرر (مثل `/tmp`). |
+
+**مثال:**
+
+```json
+{
+  "policyParams": {
+    "block-rm-rf": {
+      "allowPaths": ["/tmp", "/var/cache"]
+    }
+  }
+}
+```
+
+---
+
+### `block-curl-pipe-sh`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يرفض `curl <url> | bash`, `curl <url> | sh`, `wget <url> | bash`، والأنماط المشابهة.
+
+بدون معاملات.
+
+---
+
+### `block-failproofai-commands`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يرفض الأوامر التي ستلغي أو تعطل failproofai نفسه (مثل `npm uninstall failproofai`, `failproofai policies --uninstall`).
+
+بدون معاملات.
+
+---
+
+### `block-self-pause`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يرفض `failproofai config --pause`، الذي يوقف الإنفاذ للجلسة. الإيقاف المؤقت قرار بشري — يمكن للوكيل الذي يستطيع تشغيله إيقاف كل سياسة أخرى بأمر واحد.
+
+أضيق من [`block-failproofai-commands`](#block-failproofai-commands) بقصد، وغير مغطاة بها: تلك السياسة تستقر على حد أمر، لذلك `npx -y failproofai config --pause` لا تطابقها، وكونها واسعة غالباً ما يتم إيقاف تشغيلها حتى يتمكن الوكلاء من تشغيل `failproofai audit`. `--resume` و `--status` مسموح بهما — لا يزيل أي منهما الإنفاذ.
+
+يوقف المحاولة المباشرة، وليس الفئة كاملة: يمكن للوكيل الوصول لنفس الحالة من خلال اسم مستعار أو سكريبت wrapper. إغلاقها بالكامل يتطلب أن تكون الإيقافة غير قابلة للوصول من استدعاء أداة على الإطلاق.
+
+بدون معاملات.
+
+---
+
+## أوامر البنية التحتية
+
+منع وكلاء الكود من تشغيل CLIs البنية التحتية أو تفعيل خطوط أنابيب CI/CD. جميع السياسات في هذه الفئة **اختيارية** (`defaultEnabled: false`) — الوكلاء الذين يحتاجون بشرعية لاستدعاء `kubectl`, `terraform`، إلخ لن يُعطلوا ما لم تُفعل السياسة. عند التفعيل، كل استدعاء للـ CLI المطابق مرفوض ما لم يطابق الأمر إدخالاً في `allowPatterns`.
+
+نحو النمط هو نفس [`block-sudo`](#block-sudo): الرموز تُطابق مقابل argv المحللة، `*` بطاقة بدل لرمز واحد، وأي أمر يحتوي على مشغل shell مستقل (`&&`, `||`, `|`, `;`) أو رمز به أحرف metacharacters shell مدمجة مرفوض قبل تطابق قائمة المسموح به لمنع تجاوزات الحقن.
+
+### `block-kubectl`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يرفض أي استدعاء `kubectl`.
+
+**المعاملات:**
+
+| المعامل | النوع | الافتراضي | الوصف |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | بادئات أوامر kubectl المسموح بها. |
+
+**مثال:**
+
+```json
+{
+  "policyParams": {
+    "block-kubectl": {
+      "allowPatterns": ["kubectl get *", "kubectl describe *", "kubectl logs *"]
+    }
+  }
+}
+```
+
+مع هذا الإعداد، `kubectl get pods` مسموح لكن `kubectl apply -f deploy.yaml` مرفوض.
+
+---
+
+### `block-terraform`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يرفض أي استدعاء `terraform` أو `tofu` (OpenTofu).
+
+**المعاملات:**
+
+| المعامل | النوع | الافتراضي | الوصف |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | بادئات أوامر terraform/tofu المسموح بها. |
+
+**مثال:**
+
+```json
+{
+  "policyParams": {
+    "block-terraform": {
+      "allowPatterns": ["terraform plan", "terraform validate", "terraform show *"]
+    }
+  }
+}
+```
+
+---
+
+### `block-aws-cli`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يرفض أي استدعاء AWS CLI.
+
+**المعاملات:**
+
+| المعامل | النوع | الافتراضي | الوصف |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | بادئات أوامر AWS CLI المسموح بها. |
+
+**مثال:**
+
+```json
+{
+  "policyParams": {
+    "block-aws-cli": {
+      "allowPatterns": ["aws s3 ls *", "aws sts get-caller-identity"]
+    }
+  }
+}
+```
+
+---
+
+### `block-gcloud`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يرفض أي استدعاء CLI `gcloud` (Google Cloud).
+
+**المعاملات:**
+
+| المعامل | النوع | الافتراضي | الوصف |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | بادئات أوامر gcloud المسموح بها. |
+
+**مثال:**
+
+```json
+{
+  "policyParams": {
+    "block-gcloud": {
+      "allowPatterns": ["gcloud auth list", "gcloud config list"]
+    }
+  }
+}
+```
+
+---
+
+### `block-az-cli`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يرفض أي استدعاء CLI `az` (Azure).
+
+**المعاملات:**
+
+| المعامل | النوع | الافتراضي | الوصف |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | بادئات أوامر az CLI المسموح بها. |
+
+**مثال:**
+
+```json
+{
+  "policyParams": {
+    "block-az-cli": {
+      "allowPatterns": ["az account show", "az group list"]
+    }
+  }
+}
+```
+
+---
+
+### `block-helm`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يرفض أي استدعاء `helm`.
+
+**المعاملات:**
+
+| المعامل | النوع | الافتراضي | الوصف |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | بادئات أوامر helm المسموح بها. |
+
+**مثال:**
+
+```json
+{
+  "policyParams": {
+    "block-helm": {
+      "allowPatterns": ["helm list", "helm status *"]
+    }
+  }
+}
+```
+
+---
+
+### `block-gh-pipeline`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يرفض أوامر CLI `gh` الفرعية التالية التي تغير الحالة أو تفعل خطوط الأنابيب:
+
+- `gh workflow run`, `gh workflow enable`, `gh workflow disable`
+- `gh run rerun`, `gh run cancel`
+- `gh pr merge`
+- `gh release create`, `gh release delete`
+- `gh cache delete`
+- `gh secret set`, `gh secret delete`
+
+أوامر `gh` الفرعية للقراءة فقط مثل `gh pr view`, `gh pr list`, `gh run list`, `gh release view`, و `gh api repos/.../...` **لا تُطابق** بهذه السياسة — مطلوبة بشكل روتيني لفحوصات سير العمل (بما في ذلك `require-ci-green-before-stop` الخاص بـ failproofai).
+
+**المعاملات:**
+
+| المعامل | النوع | الافتراضي | الوصف |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | استدعاءات محددة بسكريبت للسماح بها حتى وإن كانت مرفوضة بخلاف ذلك. |
+
+**مثال:**
+
+```json
+{
+  "policyParams": {
+    "block-gh-pipeline": {
+      "allowPatterns": ["gh run rerun *"]
+    }
+  }
+}
+```
+
+---
+
+## الأسرار (المعالجات)
+
+منع الوكلاء من تسريب بيانات الاعتماد إلى سياقهم أو إخراجهم. تُطلق سياسات المعالج على أحداث **PostToolUse**. عند تشغيل Claude أمر Bash أو قراءة ملف أو استدعاء أي أداة، تفحص هذه السياسات الإخراج قبل إرجاعه إلى Claude. إذا تم اكتشاف نمط سر، تُرجع السياسة قرار رفض يمنع الإخراج من الإرجاع.
+
+### `sanitize-jwt`
+
+**الحدث:** PostToolUse (جميع الأدوات)  
+**الافتراضي:** يحجب توكنات JWT (ثلاثة قطاعات base64url مفصولة بـ `.`).
+
+بدون معاملات.
+
+---
+
+### `sanitize-api-keys`
+
+**الحدث:** PostToolUse (جميع الأدوات)  
+**الافتراضي:** يحجب صيغ مفاتيح API الشائعة: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), مفاتيح الوصول AWS (`AKIA`), مفاتيح Stripe (`sk_live_`, `sk_test_`), ومفاتيح Google API (`AIza`).
+
+**المعاملات:**
+
+| المعامل | النوع | الافتراضي | الوصف |
+|-------|------|---------|-------------|
+| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | أنماط regex إضافية لمعاملتها كأسرار. |
+
+**مثال:**
+
+```json
+{
+  "policyParams": {
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "مفتاح API داخلي من MyCo" },
+        { "regex": "pat_[0-9a-f]{40}", "label": "PAT داخلي" }
+      ]
+    }
+  }
+}
+```
+
+---
+
+### `sanitize-connection-strings`
+
+**الحدث:** PostToolUse (جميع الأدوات)  
+**الافتراضي:** يحجب سلاسل توصيل قاعدة البيانات التي تحتوي على بيانات اعتماد مدمجة (مثل `postgresql://user:password@host/db`).
+
+بدون معاملات.
+
+---
+
+### `sanitize-private-key-content`
+
+**الحدث:** PostToolUse (جميع الأدوات)  
+**الافتراضي:** يحجب كتل PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`، إلخ).
+
+بدون معاملات.
+
+---
+
+### `sanitize-bearer-tokens`
+
+**الحدث:** PostToolUse (جميع الأدوات)  
+**الافتراضي:** يحجب رؤوس `Authorization: Bearer <token>` حيث التوكن 20 حرف أو أكثر.
+
+بدون معاملات.
+
+---
+
+## البيئة
+
+حماية تكوين البيئة الحساسة من القراءة أو التعريض من قبل الوكلاء.
+
+### `block-env-files`
+
+**الحدث:** PreToolUse (Bash, Read)  
+**الافتراضي:** يرفض قراءة ملفات `.env` عبر `cat .env`, استدعاءات أداة Read مع `.env` كمسار الملف، إلخ.
+
+لا يحجب `.envrc` أو ملفات أخرى متعلقة بالبيئة - فقط الملفات المسماة بالضبط `.env`.
+
+بدون معاملات.
+
+---
+
+### `protect-env-vars`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يرفض الأوامر التي تطبع متغيرات البيئة: `printenv`, `env`, `echo $VAR`.
+
+بدون معاملات.
+
+---
+
+## الوصول إلى الملفات
+
+احتفظ بالوكلاء يعملون داخل حدود المشروع بعيداً عن الملفات الحساسة.
+
+### `block-read-outside-cwd`
+
+**الحدث:** PreToolUse (Read, Bash)  
+**الافتراضي:** يرفض قراءة الملفات خارج جذر المشروع. الحد هو `CLAUDE_PROJECT_DIR` (مضبوط مرة واحدة لكل جلسة بواسطة Claude Code)، مع فشل على cwd الحالي للجلسة عند عدم ضبط هذا المتغير. استخدام جذر المشروع بدلاً من `cwd` الحي يعني بقاء الحد ثابتاً حتى بعد قيام Claude بـ `cd` في مجلد فرعي.
+
+**المعاملات:**
+
+| المعامل | النوع | الافتراضي | الوصف |
+|-------|------|---------|-------------|
+| `allowPaths` | `string[]` | `[]` | بادئات المسار المطلق المسموح بها حتى خارج جذر المشروع. |
+
+**مثال:**
+
+```json
+{
+  "policyParams": {
+    "block-read-outside-cwd": {
+      "allowPaths": ["/shared/data", "/opt/company/config"]
+    }
+  }
+}
+```
+
+---
+
+### `block-secrets-write`
+
+**الحدث:** PreToolUse (Write, Edit)  
+**الافتراضي:** يرفض الكتابة إلى الملفات المستخدمة عادة للمفاتيح الخاصة والشهادات: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`.
+
+**المعاملات:**
+
+| المعامل | النوع | الافتراضي | الوصف |
+|-------|------|---------|-------------|
+| `additionalPatterns` | `string[]` | `[]` | أنماط اسم ملف إضافية (نمط glob) للحجب. |
+
+**مثال:**
+
+```json
+{
+  "policyParams": {
+    "block-secrets-write": {
+      "additionalPatterns": [".token", ".secret"]
+    }
+  }
+}
+```
+
+---
+
+## Git
+
+منع الدفع العرضي والدفع الإجباري وأخطاء الفرع التي يصعب التراجع عنها.
+
+### `block-push-master`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يرفض `git push origin main` و `git push origin master`.
+
+**المعاملات:**
+
+| المعامل | النوع | الافتراضي | الوصف |
+|-------|------|---------|-------------|
+| `protectedBranches` | `string[]` | `["main", "master"]` | أسماء الفروع التي لا يمكن الدفع إليها مباشرة. |
+
+**مثال:**
+
+```json
+{
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "master", "release", "prod"]
+    }
+  }
+}
+```
+
+<Tip>
+للسماح بالدفع إلى جميع الفروع (تعطيل هذه السياسة فعلياً دون إزالتها من `enabledPolicies`)، اضبط `protectedBranches: []`.
+</Tip>
+
+---
+
+### `block-work-on-main`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يرفض `git commit`, `git merge`, `git rebase`, و `git cherry-pick` بينما شجرة العمل على `main` أو `master`. إنشاء فرع والتبديل (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) لا تتأثر.
+
+**المعاملات:**
+
+| المعامل | النوع | الافتراضي | الوصف |
+|-------|------|---------|-------------|
+| `protectedBranches` | `string[]` | `["main", "master"]` | أسماء الفروع التي يُرفض عليها الالتزام/الدمج/إعادة الأساس/اختيار الكرز. |
+
+---
+
+### `block-force-push`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يرفض `git push --force` و `git push -f`.
+
+بدون معاملات خاصة بالسياسة. استخدم [`hint`](/ar/configuration#hint-cross-cutting) عابر المقاطع للاقتراح بدائل:
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "أنشئ فرع جديد من HEAD الحالي (مثل `git checkout -b <new-branch>`) وادفع ذلك بدلاً منه."
+    }
+  }
+}
+```
+
+---
+
+### `warn-git-amend`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يوجه Claude للمتابعة بحذر عند تشغيل `git commit --amend`. لا يحجب الأمر.
+
+بدون معاملات.
+
+---
+
+### `warn-git-stash-drop`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يوجه Claude للتأكيد قبل تشغيل `git stash drop`. لا يحجب الأمر.
+
+بدون معاملات.
+
+---
+
+### `warn-all-files-staged`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يوجه Claude لمراجعة ما يرحله عند تشغيل `git add -A` أو `git add .`. لا يحجب الأمر.
+
+بدون معاملات.
+
+---
+
+## قاعدة البيانات
+
+التقط عمليات SQL المدمرة قبل تنفيذها على قاعدة البيانات.
+
+### `warn-destructive-sql`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يوجه Claude للتأكيد قبل تشغيل SQL يحتوي على `DROP TABLE`, `DROP DATABASE`, أو `DELETE` بدون شرط `WHERE`.
+
+بدون معاملات.
+
+---
+
+### `warn-schema-alteration`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يوجه Claude للتأكيد قبل تشغيل عبارات `ALTER TABLE`.
+
+بدون معاملات.
+
+---
+
+## التحذيرات
+
+أعط الوكلاء سياق إضافي قبل عمليات محتملة المخاطر لكن غير مدمرة.
+
+### `warn-large-file-write`
+
+**الحدث:** PreToolUse (Write)  
+**الافتراضي:** يوجه Claude للتأكيد قبل كتابة الملفات الأكبر من 1024 KB.
+
+**المعاملات:**
+
+| المعامل | النوع | الافتراضي | الوصف |
+|-------|------|---------|-------------|
+| `thresholdKb` | `number` | `1024` | عتبة حجم الملف بالكيلوبايت التي تُصدر فوقها تحذير. |
+
+**مثال:**
+
+```json
+{
+  "policyParams": {
+    "warn-large-file-write": {
+      "thresholdKb": 256
+    }
+  }
+}
+```
+
+<Note>
+يفرض معالج Hook حد أقصى 1 MB لـ stdin على الأحمال. لاختبار هذه السياسة مع محتوى صغير، اضبط `thresholdKb` على قيمة أقل بكثير من 1024.
+</Note>
+
+---
+
+### `warn-package-publish`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يوجه Claude للتأكيد قبل تشغيل `npm publish`.
+
+بدون معاملات.
+
+---
+
+### `warn-background-process`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يوجه Claude للحذر عند إطلاق العمليات الخلفية عبر `nohup`, `&`, `disown`, أو `screen`.
+
+بدون معاملات.
+
+---
+
+### `warn-global-package-install`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** يوجه Claude للتأكيد قبل تشغيل `npm install -g`, `yarn global add`, أو `pip install` بدون بيئة افتراضية.
+
+بدون معاملات.
+
+---
+
+## مديري الحزم
+
+فرض مديري الحزم المسموح للوكيل باستخدامهم.
+
+### `prefer-package-manager`
+
+**الحدث:** PreToolUse (Bash)  
+**الافتراضي:** معطل. عند التفعيل، يحجب أي أمر مدير حزم ليس في قائمة `allowed` ويخبر Claude لإعادة كتابة الأمر باستخدام مدير مسموح.
+
+يكتشف: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo.
+
+| المعامل | النوع | الافتراضي | الوصف |
+|-----------|------|---------|-------------|
+| `allowed` | string[] | `[]` | أسماء مديري الحزم المسموح بها. أي مدير مكتشف ليس في هذه القائمة مرفوض. عند الفراغ، السياسة بدون عملية. |
+| `blocked` | string[] | `[]` | أسماء مديري إضافية للحجب بما يتجاوز القائمة المدمجة (مثل `['pdm', 'pipx']`). |
+
+تغطي قائمة الحجب المدمجة: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. استخدم `blocked` لإضافة مديرين ليسوا في هذه القائمة.
+
+**مثال الإعداد:**
+
+```json
+{
+  "enabledPolicies": ["prefer-package-manager"],
+  "policyParams": {
+    "prefer-package-manager": {
+      "allowed": ["uv", "bun"],
+      "blocked": ["pdm", "pipx"]
+    }
+  }
+}
+```
+
+مع هذا الإعداد، `pip install flask` و `pdm install flask` كلاهما مرفوض برسالة تخبر Claude باستخدام `uv` أو `bun` بدلاً منهما. أوامر مثل `uv pip install flask` مسموح بها لأن `uv` في قائمة المسموح به ويُفحص أولاً.
+
+---
+
+## سلوك الذكاء الاصطناعي
+
+كتشف عند عدم عمل الوكلاء أو سلوكهم بشكل غير متوقع.
+
+### `warn-repeated-tool-calls`
+
+**الحدث:** PreToolUse (جميع الأدوات)  
+**الافتراضي:** يوجه Claude لإعادة النظر عند استدعاء نفس الأداة 3+ مرات بمعاملات متطابقة - علامة شائعة على أن الوكيل عالق في حلقة.
+
+بدون معاملات.
+
+---
+
+## سير العمل
+
+فرض سير عمل منضبط لنهاية الجلسة. تُطلق هذه السياسات على حدث **Stop** وترفض الوكيل من التوقف حتى استيفاء كل شرط. تتبع سلسلة اعتماد طبيعية: commit → push → PR → CI. إذا رفضت سياسة، يتم تخطي السياسات اللاحقة في السلسلة (رفض يختصر).
+
+جميع سياسات سير العمل **فتح-الفشل**: إذا لم تكن الأداة المطلوبة متاحة (مثل `gh` غير مثبت، لا توجد git remote)، تسمح السياسة برسالة إعلامية توضح لماذا تم تخطي الفحص.
+
+### دلالات Stop لكل CLI
+
+يبدو إنفاذ Stop مختلفاً قليلاً عبر ستة CLIs المدعومة لأن كل واحد يعرض عقد hook "انتهى الوكيل" مختلف. **النتيجة** متساوية — الوكيل لا يتمكن من التوقف بينما بوابة سير العمل تفشل — لكن **الآليات** تختلف. الجدول أدناه يلخص؛ فقط Pi له quirk مرئي للمستخدم يستحق الفهم قبل تفعيل سياسة `require-*-before-stop`.
+
+| CLI | عند إطلاق البوابة | ما تراه |
+|---|---|---|
+| Claude Code | نفس حلقة الوكيل، فوراً | يستمر Claude في العمل — يصحح المشكلة، ثم يحاول الانتهاء مرة أخرى. لا انقطاع مرئي لك. |
+| Codex | نفس حلقة الوكيل، فوراً | نفس Claude. |
+| GitHub Copilot CLI | نفس حلقة الوكيل، فوراً | نفس Claude (يستخدم قناة إعادة المحاولة `{decision:"block", reason}` من Copilot — تم التحقق تجريبياً مقابل Copilot CLI 1.0.41). |
+| Cursor Agent | نفس حلقة الوكيل، فوراً | نفس Claude (يستخدم قناة Cursor `{followup_message}` — محدودة بـ `loop_limit`، افتراضي 5 محاولات إعادة). |
+| OpenCode | نفس حلقة الوكيل، فوراً | نفس Claude (يستخدم استدعاء SDK `client.session.prompt(...)` من OpenCode الموجه عبر `hookSpecificOutput.additionalContext`). |
+| **Pi (pi-coding-agent)** | **دورة المستخدم التالية** | **يتوقف Pi بشكل مرئي** عند إطلاق البوابة — حلقة وكيله تخرج وتُعاد للمحث. ثم تُطلق البوابة في المرة التالية التي تُرسل فيها محث: يضيف failproofai توجيه `MANDATORY ACTION REQUIRED` إلى نظام المحث لهذه الدورة، يوجه LLM لإكمال خطوة سير العمل (التزام، دفع، إلخ) قبل فعل ما طلبته. |
+
+<Note>
+**قيد Pi.** Pi's `AgentEndEvent` (المعادل الأعلى لـ Claude's `Stop` hook) ليس له نوع Result — بحلول وقت إطلاقه، حلقة وكيل Pi قد خرجت بالفعل. لا يمكن لـ failproofai إجبار Pi على إعادة محاولة نفس الحلقة بالطريقة التي يمكن فعلها مع Claude / Copilot / Cursor / OpenCode. يحول failproofai البوابة إلى حدث Pi's `before_agent_start` (الذي يُطلق بعد المحث التالي من المستخدم) حتى فحص سير العمل لا يزال ينفذ، فقط على الدورة التالية بدلاً من الحالية.
+
+**ما يعنيه هذا عملياً:**
+
+- بعد توقف Pi، يُحفظ سبب الرفض في الذاكرة مفتاح بـ Pi session id. المحث التالي جداً الذي تُرسله في نفس عملية Pi يستنزفه: LLM يرى توجيه `MANDATORY ACTION REQUIRED` في أعلى نظام المحث، يلتزم (أو يدفع / يفتح PR / ينتظر CI)، وفقط بعد ذلك يستمر مع طلبك. سبب الرفض المحفوظ مرة واحدة — بمجرد استنزافه، البوابة واضحة.
+- البوابة محدودة بعمر عملية Pi. إذا `Ctrl+C` Pi أو أقفلت بين الدورات، يتم حذف إدخال الذاكرة مع العملية والبوابة تُفتقد. Claude و Copilot و Cursor و OpenCode لها نفس الحد (اقتل الوكيل والبوابة تُفتقد) — Pi فقط يجعلها أكثر وضوحاً لأن الوكيل يخرج بشكل مرئي قبل إطلاق البوابة.
+- يتم مسح رفض معلق أيضاً على `session_shutdown` لأي سبب (`new` / `resume` / `fork` / `quit`)، حتى بوابة قديمة من جلسة سابقة لا تتسرب إلى جلسة جديدة بدأت في نفس عملية Pi.
+
+إذا كنت بحاجة إلى إعادة محاولة نفس حلقة على غرار Claude، شغل سياسات `Stop` تحت أي من الخمسة CLIs المدعومة الأخرى. نحن نتتبع Pi الأعلى لنوع Result مستقبلي على `AgentEndEvent` الذي سيسمح لنا بإغلاق هذا الفجوة.
+</Note>
+
+### `require-commit-before-stop`
+
+**الحدث:** Stop  
+**الافتراضي:** يرفض التوقف عند وجود تغييرات غير مرحلة (ملفات معدلة، مرحلة، أو غير متتبعة). يرجع رسالة إعلامية عند كون مجلد العمل نظيفاً.
+
+بدون معاملات.
+
+---
+
+### `require-push-before-stop`
+
+**الحدث:** Stop  
+**الافتراضي:** يرفض التوقف عند وجود التزامات غير مدفوعة أو عند عدم وجود فرع تتبع بعيد للفرع الحالي. يقترح `git push -u` لإنشاء فرع تتبع إن لزم. يفشل مفتوحاً إذا لم يكن remote مُعد.
+
+**المعاملات:**
+
+| المعامل | النوع | الافتراضي | الوصف |
+|-------|------|---------|-------------|
+| `remote` | `string` | `"origin"` | اسم الـ remote للدفع إليه. |
+
+**مثال:**
+
+```json
+{
+  "policyParams": {
+    "require-push-before-stop": {
+      "remote": "upstream"
+    }
+  }
+}
+```
+
+---
+
+### `require-pr-before-stop`
+
+**الحدث:** Stop  
+**الافتراضي:** يرفض التوقف عند عدم وجود طلب سحب للفرع الحالي، أو عند إغلاق طلب السحب الموجود دون دمج. يوجه Claude لإنشاء PR مع `gh pr create`. عند **دمج** PR، تسمح السياسة (الشغل شحن) والرسالة تلمح للتبديل خارج الفرع (`git checkout main && git pull`).
+
+بدون معاملات.
+
+<Note>
+تتطلب هذه السياسة [GitHub CLI](https://cli.github.com/) (`gh`) مثبتاً ومصرحاً.
+شغل `gh auth login` مع رمز وصول شخصي يمتلك نطاق `repo` للوصول القراءة
+إلى طلبات السحب. إذا لم يكن `gh` مثبتاً أو مصرحاً، تفشل السياسة مفتوحة وتبلغ السبب إلى Claude.
+</Note>
+
+---
+
+### `require-no-conflicts-before-stop`
+
+**الحدث:** Stop  
+**الافتراضي:** يرفض التوقف عند عدم القدرة على دمج الفرع الحالي نظيفاً في فرع الأساس. تؤكد السياسة أولاً وجود PR `OPEN` على GitHub للفرع — بدون واحد، لا يوجد هدف دمج لفرضه، لذلك السياسة بأكملها تختصر للسماح. بمجرد تأكيد PR `OPEN`، تُشغل اثنان من المحاولات المستقلة:
+
+1. **محلي** — `git merge-tree --write-tree --name-only origin/<baseBranch> HEAD`. عند التعارض، رسالة الرفض تُسمي الملفات المتعارضة حتى يعرف Claude بالضبط ما يجب حله.
+2. **GitHub** — يُعيد استخدام نتيجة `gh pr view --json mergeable,state` المجلوبة بالفعل في الفحص المسبق. يمسك التعارضات التي قد يفتقدها `origin/<baseBranch>` المحلي القديم (مثل هبوط شخص ما PR متعارض على `main` منذ الجلب الأخير). نتيجة `CONFLICTING` ترفض. نتيجة `UNKNOWN` أيضاً ترفض وتوجه Claude للانتظار ~10 ثواني وإعادة فحص قبل محاولة التوقف مرة أخرى — يمنع هذا النتائج السالبة الكاذبة بينما تُعيد GitHub الحساب.
+
+تتخطى بالكامل (تسمح) عند: `gh` غير مثبت، لا يوجد PR للفرع، حالة PR ليست `OPEN` (مثل `MERGED`, `CLOSED`)، أو `gh pr view` يُرجع إخراج غير قابل للتحليل. تفشل أيضاً مفتوحة عند فقدان `origin/<baseBranch>` محلياً أو عند عدم وجود التزامات قبل الأساس — تلك تسقط الطبقة 1 لا تزال تستشير mergeable المخزن مؤقتاً للـ PR قبل السماح.
+
+**المعاملات:**
+
+| المعامل | النوع | الافتراضي | الوصف |
+|-------|------|---------|-------------|
+| `baseBranch` | `string` | `"main"` | فرع الأساس للتحقق عن التعارضات ضده. |
+
+<Note>
+GitHub CLI (`gh`) مطلوب لهذه السياسة. تستخدم السياسة `gh pr view` لتأكيد
+وجود PR `OPEN` قبل تشغيل أي محاولة تعارض — بدون `gh`، تختصر السياسة
+للسماح. شغل `gh auth login` مع رمز وصول شخصي يمتلك نطاق `repo` للوصول القراءة
+إلى طلبات السحب.
+</Note>
+
+---
+
+### `require-ci-green-before-stop`
+
+**الحدث:** Stop  
+**الافتراضي:** يرفض التوقف عند فشل فحوصات CI أو لا تزال قيد التشغيل على الفرع الحالي. يفحص كلاً من تشغيلات سير العمل GitHub Actions والفحوصات من جهات خارجية (مثل CodeRabbit، SonarCloud، Codecov). يعامل الخلاصات `skipped`, `cancelled`, و `neutral` كغير فاشلة (الأخيرة تغطي مثل Socket Security تنبيهات على PRs المساهمة الخارجية، حيث التطبيق بقصد يُبلغ محايد بدلاً من النجاح/الفشل). يرجع رسالة إعلامية عند نجاح جميع الفحوصات.
+
+بدون معاملات.
+
+<Note>
+تتطلب هذه السياسة [GitHub CLI](https://cli.github.com/) (`gh`) مثبتاً ومصرحاً.
+شغل `gh auth login` مع رمز وصول شخصي يمتلك نطاق `repo` للوصول القراءة
+إلى تشغيلات سير العمل Actions و Checks API. إذا لم يكن `gh` مثبتاً أو مصرحاً، تفشل السياسة مفتوحة وتبلغ السبب إلى Claude.
+</Note>
+
+---
+
+---
+
+## تعطيل السياسات الفردية
+
+أزل سياسة معينة من `enabledPolicies` في إعدادك، أو بدل تشغيلها في تبويب Policies بالـ dashboard.
+
+```json
+{
+  "enabledPolicies": [
+    "block-rm-rf",
+    "sanitize-api-keys"
+  ]
+}
+```
+
+السياسات غير المدرجة في `enabledPolicies` لا تعمل، حتى إذا كانت هناك إدخالات `policyParams` لها.