GOAP Planner — Goal-Oriented Action Planning (skill أصيل)

> الأصل: بُني نظيفاً بالكامل عندنا (A في فضاء الحالات)، مستلهَم من فكرة goal.ruv.io (Ruflo) دون تثبيت Ruflo أو أي من سلبياته (لا daemon، لا hooks، لا 61.5K توكن schema، لا دهس هوية، لا monetization). صفر تبعية خارجية — Python قياسي فقط.

ما يفعله

يحوّل هدفاً (بالعربية أو الإنجليزية) + حالة العالم الحالية إلى خطة مرتّبة قابلة للتنفيذ — تسلسل أفعال صحيح هندسياً (كل فعل يحترم شروطه المسبقة)، مع أقل تكلفة (A optimal) + مدة تقديرية + zoning.

القيمة العملية المباشرة لد. وائل (KCPC):

• Method Statements — توليد تسلسل تنفيذ منهجي صحيح تلقائياً.
• Work sequence planning — سلسلة الأعمال لمشاريع الإسكان/التطوير.
• Zoning — كل فعل موسوم بمنطقته (sub/super/mep/finish/ext/handover).
• Resume mid-project — يخطّط من أي نقطة (ما أُنجز يُتخطّى).
• Diagnostics — هدف غير قابل للتحقيق → يخبرك أي حقائق لا يُنتجها أي فعل.

الاستخدام

cd skills/goap-planner/scripts
python3 goap_cli.py plan --goal handover              # المشروع الكامل → التسليم
python3 goap_cli.py plan --goal تسليم                 # عربي مدعوم
python3 goap_cli.py plan --goal frame                 # هدف جزئي (الهيكل فقط)
python3 goap_cli.py plan --goal frame --have foundation,wp_sub,...   # استئناف
python3 goap_cli.py plan --goal handover --json       # مخرَج JSON للأتمتة
python3 goap_cli.py goals                             # الأهداف المتاحة + الأسماء العربية
python3 goap_cli.py selftest                          # 29 اختبار (E2E + red-team)

البنية (3 ملفات، نظيفة)

• scripts/goap_engine.py — محرّك A عام (State=frozenset، Action=pre/eff/cost، planner). قابل لإعادة الاستخدام لأي مجال.
• scripts/kcpc_domain.py — مكتبة أفعال هندسية حقيقية (28 فعل: mobilize→dewatering→excavate→foundation→frame→MEP→finishes→handover + متوازيات).
• scripts/goap_cli.py — واجهة CLI + محلّل أهداف (aliases عربي/إنجليزي).

التوسّع لمجالات أخرى

أضف <domain>_domain.py فيه دالة تُرجع list[Action]، وسجّله في DOMAINS بـgoap_cli.py. يصلح لأي تخطيط تبعيات (برمجة، أبحاث، لوجستيات...).

الضمانات (مُثبَتة E2E)

• 29 اختبار = صفر فشل (selftest): 19 E2E (ثوابت هندسية: mobilize قبل excavate، foundation قبل frame، handover أخيراً...) + 10 red-team (حلقات لا تتوقف، مدخلات فاسدة، optimality، أداء 14ms).
• A optimal (heuristic مقبول) + حتمي (نفس المدخل → نفس الخطة) + آمن (لا حلقات لانهائية، حدّ توسّعات).
• صفر سلبية على بنيتنا: لا يمسّ config/hooks/daemon/هوية؛ ملفات معزولة تحت skills/goap-planner/.

قاعدة الاستخلاص الآمن (Zero-Downside Harvest)

هذا نموذج منهجنا: نأخذ الفكرة** من مشروع خارجي ونبنيها أصيلة نظيفة عندنا، دون تثبيت النظام ودون أي سلبية تفقدنا شيئاً قوياً موجوداً.