From eadcd269f44b78d24704170a9bc057061a32f90b Mon Sep 17 00:00:00 2001 From: Sami Assiri Date: Thu, 16 Apr 2026 07:42:15 +0300 Subject: [PATCH] chore(docs): commit all remaining architectural documents and matrices --- Architecture_Pack.md | 119 ++++++++++++++++++++++++++++++++++++++++ Execution_Matrix.md | 114 ++++++++++++++++++++++++-------------- GitHub_Delivery_Pack.md | 67 ++++++++++++++++++++++ 3 files changed, 259 insertions(+), 41 deletions(-) create mode 100644 Architecture_Pack.md create mode 100644 GitHub_Delivery_Pack.md diff --git a/Architecture_Pack.md b/Architecture_Pack.md new file mode 100644 index 00000000..2fc8ec84 --- /dev/null +++ b/Architecture_Pack.md @@ -0,0 +1,119 @@ +# Dealix Sovereign Growth OS: Master Architecture Pack + +يمثل هذا المستند البنية الهندسية (Architecture Backbone) لتحويل Dealix من "نظام أتمتة مبيعات" إلى "نظام تشغيل نمو سيادي" (Level 5 Autonomy for Holding & Enterprise Scaling). + +--- + +## 1. 🗺️ خريطة الخدمات (Service Map) + +النظام مقسم إلى 8 طبقات تشغيلية لضمان عدم حدوث تداخلات أو اتخاذ قرارات بدون رقابة. + +### الأجزاء والعناصر + +1. **Signal Intelligence Layer (طبقة الاستشعار)** + - `Market Signal Ingestor`: ويب سكرابر + News APIs للقطاعات. + - `CRM/ERP Webhooks`: مراقبة الحالة (Pipeline, Billing). +2. **Knowledge & Memory Layer (طبقة المعرفة)** + - `Vector Store (Pinecone/Milvus)`: تخزين تاريخ المفاوضات والعقود والمذكرات. + - `Redis Store`: حالة العمليات (State Machine Status). +3. **Reasoning & Prioritization Engine (طبقة اتخاذ القرار)** + - `Agent Executor / LLM Gateway`: (محرك التنفيذ المركزي للـ 16 وكيلًا). + - `Scoring Engine`: لتقييم المزايا المالية لكل خطوة استراتيجية. +4. **Workflow Orchestration (طبقة ضبط المسارات)** + - `LangGraph / Celery Orchestrator`: للـ Long-running workflows (كالفحص النافي للجهالة الذي يطول أسابيع). + - `Event Bus (Kafka/RabbitMQ)`: لمعالجة الأحداث (Event Taxonomy 2.0). +5. **Policy & Governance Layer (طبقة الحوكمة)** + - `Policy-as-Code Engine`: يقوم بإغلاق أو تمرير التنفيذات بناءً على الموافقات والمخاطر. +6. **Execution Action Layer (طبقة الأفعال)** + - `Dispatcher`: WhatsApp, Email, DocGen (للعقود والأوراق)، ERP/CRM Integrations. +7. **Analytics & Learning Loop (طبقة التعلم)** + - `Forecast vs Actual Model`: لمقارنة توقعات الذكاء (مثلاً: أرباح الشراكة) مع الأرقام الفعلية بالمحاسبة، لتصحيح النماذج التنبؤية. +8. **Executive Cockpit (لوحة الإدارة العليا)** + - واجهة Board Members (مذكرات، Heatmaps، تصعيد). + +--- + +## 2. 📊 مخطط الأحداث ومكائن الحالة (State & Event Diagrams) + +تتغير حالة الكيان من خلال أحداث مسجلة في (Event Bus) يقرأها النظام عبر `router.py`. + +### State Machine: M&A Lifecycle (مثال) + +```mermaid +stateDiagram-v2 + [*] --> Target_Detected: signal.acquisition_candidate_detected + Target_Detected --> Shortlisted: ma.screening_completed (Fit Score > 80%) + Target_Detected --> Rejected: ma.screening_completed (Fit Score < 80%) + + Shortlisted --> Due_Diligence: ma.outreach_initiated + Due_Diligence --> Valuation: ma.dd_started (No Critical Red Flags) + Due_Diligence --> Blocked_DD: ma.red_flag_critical + + Blocked_DD --> Board_Review: governance.hitl_required + Board_Review --> Valuation: governance.hitl_approved (Override) + Board_Review --> Rejected: governance.hitl_rejected + + Valuation --> Negotiation_Live: ma.offer_strategy_ready & ma.ic_decision_required + Negotiation_Live --> Signed: ma.deal_signed + Signed --> PMI_Integration: ma.integration_started + PMI_Integration --> Synergy_Tracking: ma.close_completed + Synergy_Tracking --> [*] +``` + +--- + +## 3. 🗄️ نموذج البيانات (Data Model - Entity Graph) + +يتم ربط كل عنصرในDealix برسم بياني (Graph) لمنع تبعثر المعرفة: + +- **Entity Model (الكيان)**: (مثل 회사 "ألف") يمكن أن يكون في نفس الوقت (شريك محتمل) أو (هدف استحواذ) أو (عميل). +- **Initiative Model (المبادرات)**: يربط الخطط التنفيذية المتفرعة من M&A أو التوسع بالـ (Tasks). +- **Decision Memo Model (מذكرات القرار)**: الكيان الأهم ويحتفظ بـ: + - `memo_id` + - `agent_id` + - `decision_context` + - `financial_impact_sar` + - `audit_trail_hash` + - `status` (pending, approved, executed, rejected, rolled-back). + +--- + +## 4. 🔏 مصفوفة الصلاحيات والموافقات (Approval & Governance Matrix) + +لا توجد قرارات "صامتة" في مستوى السيادة. + +| فئة القرار (Decision Class) | وكيل التوصية (Agent) | محرك السياسة (Policy Check) | موافقة (HITL Gate) | المسار حال الرفض (Rollback) | +| :--- | :--- | :--- | :--- | :--- | +| **دخول سوق جديد** | Expansion Playbook | PDPL compliance, Legal checks | **CEO & Board** | حفظ التقرير + وقف الصرف المالي | +| **استحواذ > 1 مليون ريال** | Valuation & Synergy | Budget Validation, Due Diligence OK | **Board of Directors** | إعادة تقييم السعر / إلغاء التفاوض | +| **حملة تسويق آلي C-Level** | Exec. Outreach | Frequency Cap (لا تزعج CEO مرتين) | **VP Sales** | تغيير التوقيت / الصياغة | +| **هيكلة شراكة مع منافس** | Alliance Structuring | Anti-monopoly risk | **CEO + Legal** | استبعاد الشراكة / تغيير الهيكل لـ Referral | + +--- + +## 5. 🚀 مراحل التنفيذ المعماري (Implementation Phases) + +### ✅ Phase 1: Operating Backbone (الأيام 0 - 30) +**الهدف**: تأسيس أساس الـ OS الذي ستبنى عليه كل الوكلاء الجدد. +1. بناء `Decision Memo Engine` (الـ Standard Contract الجديد). +2. تطبيق الـ `Event Schema v2.0` داخل نظام التوجيه. +3. إنشاء `Policy-as-Code Engine` للموافقات (Approval Gates). +4. تفعيل أول 4 وكلاء (Strategic PMO, Lead Intel, Exec Outreach, Scout). + +### ✅ Phase 2: Revenue & Alliance Flywheel (الأيام 30 - 60) +**الهدف**: تشغيل دورة الإيرادات والشراكات بشكل ذكي ومحوكم. +1. تفعيل وكلاء الشراكات (Alliance Structuring). +2. إطلاق `Partner ROI Model` لوزن أي شراكة فورياً. +3. إتمام الدائرة بين الـ Proposal Design ودفع العميل عبر CRM. + +### ✅ Phase 3: Coporate Development & M&A (الأيام 60 - 90) +**الهدف**: تجهيز غرفة الإدارة الذكية للنمو غير العضوي (Inorganic Growth). +1. بناء وإطلاق وكلاء الـ M&A (Screener, DD Analyst, Valuation). +2. تفعيل غرفة اتخاذ القرار الافتراضية (Decision Room) للـ Board. +3. تفعيل الـ PMI Engine لضمان الدمج العضوي بعد الصفقة. + +### ✅ Phase 4: Sovereign Scale (الأيام 90 - 120) +**الهدف**: رؤية סיادية للمجموعة وإدارة المحفظة واستدراك الأخطاء. +1. تفعيل العميل الأعلى **Sovereign Intelligence Agent**. +2. تفعيل نظام `Forecast Vs. Actual` للتعلم الآلي (Self-Correction Loop). +3. إطلاق ميزة الـ Portfolio Dashboard لكافة مجموعة الأعمال (Holding Level). diff --git a/Execution_Matrix.md b/Execution_Matrix.md index b7e010ad..3dabd19d 100644 --- a/Execution_Matrix.md +++ b/Execution_Matrix.md @@ -1,47 +1,79 @@ -# Execution Matrix (مصفوفة التنفيذ) — Dealix Autonomous OS +# Dealix Sovereign Growth OS — Master Execution Matrix -هذا الدليل يمثّل المرجعية التشغيلية النهائية لقيادة النظام بشكل فعلي. يربط بين الوكيل، المدخلات، الأدوات، الأحداث، المخرجات، مؤشرات الأداء (KPIs)، المسؤول (Owner)، واتفاقية مستوى الخدمة (SLA). - -## 1. 🔹 مجموعة نمو المبيعات (Sales Growth Core) - -| الوكيل (Agent) | المدخلات (Inputs) | الجوانب التقنية / الأدوات (Tools) | الحدث (Event) | المخرجات (Outputs) | مؤشرات الأداء (KPIs) | المسؤول التنفيذي (Owner) | SLA | -| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | -| **Outreach Writer** | بيانات CRM، نية الشراء، قطاع العميل | API واتساب / إيميل / لينكدإن | `lead.created` | رسائل تواصل مخصصة عالية التحويل | Open Rate (>35%)، Reply Rate (>15%) | Head of Sales | فورًا | -| **Closer/Negotiator** | تاريخ المحادثات، العرض، الميزانية المتوقعة | CRM، محرك صياغة العقود | `negotiation.started` | سيناريوهات الإغلاق، شروط مقبولة (ZOPA) | Time-to-Close، Deal Win Rate (>25%) | Sales VP | ساعتان | -| **Customer Success** | صحة الحساب، استخدام المنتج، تذاكر الدعم | CRM، نظام الدعم، أدوات القياس (Mixpanel/Amplitude) | `customer.health_drop` | توصيات لمنع التسرب، خطة Upsell دورية | Net Revenue Retention (>110%)، Churn Rate (<2%) | CS Director | يوم واحد | - -## 2. 🔹 مجموعة الشراكات والتحالفات (Partnerships Core) - -| الوكيل (Agent) | المدخلات (Inputs) | الجوانب التقنية / الأدوات (Tools) | الحدث (Event) | المخرجات (Outputs) | مؤشرات الأداء (KPIs) | المسؤول التنفيذي (Owner) | SLA | -| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | -| **Partnership Scout** | اتجاهات القطاع، شركات مكملة، قواعد البيانات | Web Scraper، قاعدة شركاء Dealix | `growth.market_expansion` | قائمة الشركاء المرشحين، التقييم الأولي | Partnerships Pipeline Value | VP of Partnerships | 3 أيام | -| **Alliance Structuring** | التقييم الأولي، ملف الشريك، الاستراتيجية | قوالب قانونية، محرك نمذجة مالية | `partnership.model_recommended` | Term Sheet، النموذج المالي، تقييم المخاطر | Partner ROI، Time-to-Term-Sheet | VP of Partnerships | 5 أيام | - -## 3. 🔹 مجموعة الاستحواذات والنمو الاستراتيجي (M&A and Strategic Growth) - -| الوكيل (Agent) | المدخلات (Inputs) | الجوانب التقنية / الأدوات (Tools) | الحدث (Event) | المخرجات (Outputs) | مؤشرات الأداء (KPIs) | المسؤول التنفيذي (Owner) | SLA | -| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | -| **M&A Target Screener** | استراتيجية التوسع، بيانات مالية عامة عن الأسواق | أدوات ذكاء الأعمال المالي | `ma.target_detected` | تصنيف الأهداف، Go/No-Go الأولي | Time-to-Evaluate، Target Fit Score | M&A Director / CEO | أسبوع | -| **DD Analyst** | القوائم المالية الأولية، معلومات الفريق، التراخيص | VDR (غرفة البيانات الافتراضية)， أدوات الامتثال | `ma.screening_completed` | تقرير العناية الواجبة (Risk Matrix) المالي والتشغيلي | DD Accuracy، DD Cycle Time | CFO / Legal Advisor | أسبوعان | -| **Valuation & Synergy** | تقارير DD، التدفقات النقدية التاريخية، الافتراضات | محرك نمذجة متقدم (DCF الخ) | `ma.valuation_ready` | القيمة العادلة (Blended Valuation)， سيناريوهات العرض | Valuation Accuracy vs Market، ROI | CFO / Board | 3 أيام | -| **Executive Negotiator** | القيمة العادلة المقترحة، تحليل الطرف الآخر (Motivations) | محرك التفاوض وبناء السيناريوهات | `ma.offer_strategy_ready` | خطة التفاوض التنفيذية (BATNA, ZOPA) | Deal Win Rate، Terms Favorability | CEO / Board | يومان | -| **PMI (Integration)** | خطط الصفقة الأصلية، هيكل الشركة، الأنظمة التشغيلية | أدوات إدارة المشاريع (Asana/Jira API) | `ma.integration_kickoff` | خطة 30/60/90 يوم، تتبع التآزر | Synergy Realization Rate، Integration Speed | Integration Ops | مستمر | - -## 4. 🔹 مجموعة الحوكمة والذكاء السيادي (Governance & Apex Core) - -| الوكيل (Agent) | المدخلات (Inputs) | الجوانب التقنية / الأدوات (Tools) | الحدث (Event) | المخرجات (Outputs) | مؤشرات الأداء (KPIs) | المسؤول التنفيذي (Owner) | SLA | -| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | -| **Strategic PMO** | القرارات الإدارية العليا، خطط التوسع | API PM Tools | `growth.milestone_achieved` | تحويل الاستراتيجية لمهام فردية ومتابعة المنجزات | Initiative on-time delivery | Chief of Staff | يومي | -| **Sovereign Intelligence** | **كل مخرجات الوكلاء الـ 36 المتبقين** | Dashboard، BI Data Warehouse | `board_briefing_requested` | مذكرة رفع للمجلس، التقييم السيادي الشامل (Top Risks/Opps) | Company Growth Target، Decision Latency | **Board of Directors** | أسبوعي/شهري | +تمثل هذه المصفوفة المحرك التشغيلي (Operational Backbone) للكيان، حيث توضح كل التفاصيل التنفيذية لتشغيل الـ 16 وكيلًا عبر 4 عائلات استراتيجية لضمان التنفيذ الدقيق وفق بنية النظام (Decision Rules, HITL, Memory, SLAs). --- -### 🛡️ خطة الحوكمة والتحكم (HITL - Human In The Loop) +## 1️⃣ العائلة الأولى: ذكاء الفرص والنمو (Opportunity & Growth Intelligence) -**كل العمليات أدناه مشفرة لكي تتوقف وتطلب موافقة بشرية (HITL):** +| الوكيل (Agent) | الغرض (Purpose) | المدخلات (Inputs) | الذاكرة (Memory) | الأدوات (Tools) | أحداث الاستلام (Events In) | أحداث الإصدار (Events Out) | قواعد القرار (Decision Rules) | المخرجات (Outputs) | الـ KPIs | المالك (Owner) | SLA | بوابة التحكم (HITL Gate) | +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | +| **1. Market Signal Agent** | رصد إشارات السوق والقطاع والمنافسين | إشارات السوق، مصادر الأخبار، تقارير القطاع | Entity Memory (Competitors, Sectors) | Web Scraper, News APIs, Crunchbase | السحب المجدول يومياً | `signal.market_shift_detected`
`signal.competitor_move_detected` | تصنيف الإشارة كتهديد/فرصة بناءً على Threshold | Market Opportunity Brief, Urgency Index | False-positive rate, Signal relevance | VP Strategy | 4 ساعات | ❌ لا يوجد (Auto) | +| **2. Partnership Scout** | رصد وتصنيف الشركاء المحتملين | بيانات الشركات المكملة، إشارات الأسواق | Partner Memory | Web Scraper, LinkedIn API, CRM | `signal.partner_interest_detected` | `partnership.scouted`
`partnership.scored` | استبعاد الشركاء خارج القطاعات المستهدفة | Partner Scorecard, Fit Analysis | Partner sourced pipeline, Scout-to-sign time | VP Partnerships | 24 ساعة | ❌ لا يوجد | +| **3. Alliance Structuring** | بناء النماذج المالية والتشغيلية للتحالفات | ملف الشريك، استراتيجية النمو، قواعد التحالف | Deal Memory | النمذجة المالية، قوالب العقود | `partnership.fit_confirmed` | `partnership.structure_simulated`
`partnership.term_sheet_prepared` | تحديد هيكل يحقق ROI > 150% خلال 12 شهر | P&L Simulation, Term Sheet Draft, Risk Register | Parnter ROI, Time-to-Term-Sheet | VP Partnerships | 48 ساعة | 🛑 إرسال Term Sheet | +| **4. Expansion Playbook** | إدارة دخول أسواق جديدة وتجهيز خطة الإطلاق | تقييم الأسواق، المتطلبات القانونية، تكلفة العمالة | Market Memory | TAM/SAM/SOM Calculator, Compliance DB | `growth.market_candidate_identified` | `growth.entry_mode_recommended`
`growth.playbook_generated` | لا يتم الإطلاق إلا بتحقيق Positive Cashflow < 18 شهر | Launch Milestones, Localization Cost, Capex | Time to Launch, Launch-to-breakeven | GM Expansion |سبوع واحد | 🛑 اعتماد الميزانية | -* توقيع **Term Sheet** مع شريك. -* إصدار أي **Go/No-go** لعملية استحواذ (DD). -* الموافقة على **تقييم مالي أعلى من 1,000,000 ريال**. -* إطلاق **PMI (التكامل بعد الاستحواذ)**. -* أي حالة تُسند لـ **Sovereign Intelligence Agent** مع علامة قنطرة (Critical/Break-glass). +--- + +## 2️⃣ العائلة الثانية: التطوير المؤسسي والاستحواذات (Corporate Development & M&A) + +| الوكيل (Agent) | الغرض (Purpose) | المدخلات (Inputs) | الذاكرة (Memory) | الأدوات (Tools) | أحداث الاستلام (Events In) | أحداث الإصدار (Events Out) | قواعد القرار (Decision Rules) | المخرجات (Outputs) | الـ KPIs | المالك (Owner) | SLA | بوابة التحكم (HITL Gate) | +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | +| **5. M&A Target Screener** | فرز وتقييم فرص الاستحواذ مبدئيًا | القوائم المالية الأولية، التآزر الجغرافي والمنتجات | Entity Memory (Targets) | Financial Data API | `signal.acquisition_candidate_detected` | `ma.screening_completed`
`ma.shortlisted` | رفض أي هدف لديه ديون تفوق 3x EBITDA | Target Fit Score, Go/No-Go الأولي | Screened-to-shortlist % | M&A Director | 3 أيام | ❌ لا يوجد | +| **6. DD Analyst** | تنسيق الفحص النافي للجهالة الشامل | الوثائق القانونية، الجداول المالية، عقود الموظفين | Deal Memory | VDR integration, Compliance checker | `ma.outreach_initiated` | `ma.dd_started`
`ma.dd_issue_logged`
`ma.red_flag_critical` | تصعيد فوري عند اكتشاف أي خرق للـ PDPL أو الاحتيال | Risk Matrix, DD Report | DD Turnaround Time, DD Accuracy | CFO | 10 أيام | 🛑 الموافقة على تخطي العلامات الحمراء | +| **7. Valuation & Synergy** | تقييم القيمة العادلة وعوائد التآزر (Rev/Cost) | تقارير الفحص (DD)، تدفقات نقدية | Deal Memory | محرك تقييم (DCF, Multiples) | `ma.dd_started` | `ma.valuation_ready`
`ma.synergy_variance_detected` | تقديم 3 سيناريوهات للتقييم على الأقل (Base/Bull/Bear) | Valuation Range, Synergy NPV, Payback | Valuation accuracy, Synergy realization % | CFO | 4 أيام | 🛑 الموافقة على التقييم الأولي | +| **8. Deal Structuring & Negotiation** | بناء هيكل الصفقة الجانب التفاوضي (BATNA) | التقييم المعاير، أهداف المالكين للمستهدف | Deal Memory | Negotiation Tree Builder | `ma.valuation_ready` | `ma.offer_strategy_ready`
`ma.offer_submitted`
`ma.deal_signed` | عدم تجاوز الحد الأعلى للسعر دون موافقة الإدارة | LOI Draft, BATNA, Walk-away thresholds | Offer-to-close %, Terms Favorability | CEO | يومان | 🛑 تقديم عرض الاستحواذ النهائي | +| **9. Post-Merger Integration (PMI)** | التكامل وتتبع نجاح الاستحواذ 30/60/90 يوم | خطط التكامل، هيكلة الفرق، الأنظمة | Deal Memory | Asana/Jira API, ERP API | `ma.close_completed` | `ma.integration_started`
`ma.synergy_variance_detected` | تنبيه الإدارة حال تأخر اندماج الـ IT أكثر من 15 يوم | PMI 30/60/90 Plan, Day 1 Readiness | Time-to-stability, Synergy realization % | Integration Ops| مستمر | 🛑 إعلان اكتمال الدمج | + +--- + +## 3️⃣ العائلة الثالثة: العمليات التجارية والإيرادات (Revenue & Commercial Operations) + +| الوكيل (Agent) | الغرض (Purpose) | المدخلات (Inputs) | الذاكرة (Memory) | الأدوات (Tools) | أحداث الاستلام (Events In) | أحداث الإصدار (Events Out) | قواعد القرار (Decision Rules) | المخرجات (Outputs) | الـ KPIs | المالك (Owner) | SLA | بوابة التحكم (HITL Gate) | +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | +| **10. Lead Intelligence** | تأهيل وتصنيف العملاء ونيات الشراء | CRM data، زيارات الموقع، Intent data | Entity Memory (Accounts) | Clearbit, Lusha, CRM API | `lead.created` | `lead.enriched`
`lead.scored` | توجيه الحسابات الأعلى من مليون ريال للمبيعات التنفيذية مباشرة | Lead Fit Score, Intent Level | Qualified pipeline growth | Head of Sales | 10 دقائق| ❌ لا يوجد | +| **11. Executive Outreach** | تنسيق حملات التواصل التنفيذي المتعددة القنوات | سجل التواصل، ملف العميل، توقيت الاتصال | Contact Memory | WhatsApp API, Email API | `lead.scored` | `outreach.initiated`
`outreach.replied` | لا يتم إرسال رسالة تنفيذية دون توافر شخصية العميل (Persona) | Personalization Text, Cadence Plan | Reply Rate, Sales cycle compression | Head of Sales | 1 ساعة | 🛑 الحملات الجماعية للشركاء وكبار العملاء | +| **12. Proposal & Commercial Design** | تسعير العروض وهيكلة الحزم التجارية للشركات | متطلبات العميل، تسعير المنافسين، هوامش الربح | Deal Memory | CPQ, PDF Generator | `meeting.completed` | `proposal.drafted`
`proposal.sent` | الحفاظ على هامش ربح لا يقل عن 60% لكل عقد | Pricing Architecture, Enterprise Proposal | Win rate by segment, Gross margin | VP Sales | 4 ساعات | 🛑 خصم يزيد عن 20% | +| **13. Customer Expansion** | صيانة الحسابات المكتسبة وفرص زيادة المبيعات | استخدام النظام، صحة الحساب، التذاكر | Account Memory | Billing API, Mixpanel | `customer.health_drop`
`customer.renewal_approaching` | `expansion.opportunity_identified`
`expansion.churn_risk_flagged` | إطلاق حملة الاحتفاظ فور نزول الـ Health Score لـ Amber | Upsell Plan, Account Health Brief | Net Revenue Retention, Churn rate | CS Director | 24 ساعة | ❌ لا يوجد | + +--- + +## 4️⃣ العائلة الرابعة: الحوكمة، التنفيذ والتعلم (Governance, Execution & Learning) + +| الوكيل (Agent) | الغرض (Purpose) | المدخلات (Inputs) | الذاكرة (Memory) | الأدوات (Tools) | أحداث الاستلام (Events In) | أحداث الإصدار (Events Out) | قواعد القرار (Decision Rules) | المخرجات (Outputs) | الـ KPIs | المالك (Owner) | SLA | بوابة التحكم (HITL Gate) | +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | +| **14. Strategic PMO** | تفتيت المبادرات إلى مهام، ومتابعة الجدول الزمني | المذكرة الاستراتيجية، الميزانيات، الفريق | Initiative Memory| Jira/Asana API | `growth.launch_authorized`
`execution.milestone_due` | `execution.plan_created`
`execution.escalation_triggered` | تصعيد المهام المتأخرة أكثر من أسبوعين فورًا للـ Executive | Workstreams, Owners assignments, RAG status | Initiative on-time rate, critical path slippage | Chief of Staff| يومي | 🛑 تعديل الميزانيات الرئيسية | +| **15. Policy & Compliance** | تطبيق السياسات، الحماية من المخاطر وضمان PDPL | أي حدث حساس يُولد عبر النظام (Term sheet, Email list) | Policy Memory | Policy Engine, Audit Ledger | `governance.hitl_required` | `governance.policy_check_passed`
`governance.policy_violation_detected` | الحظر الفوري لأي إجراء يخترق الـ PDPL (حماية البيانات) | Compliance Check Report, Audit Snapshot | Policy violation rate, Audit completeness | Compliance Officer | ثواني | 🛑 استثناء قواعد الامتثال أو التخطي (Override) | +| **16. Executive Intelligence (Sovereign)** | بناء النظرة الشمولية وتوجيه مجلس الإدارة والقيادة | مذكرات قرارات الوكلاء الـ 15، تنبيهات، ماليات | Sovereign Memory| BI Engine, Dashboard | `board_briefing_requested`
`ma.board_decision_required` | `strategic.action_recommended`
`strategic.capital_allocated` | إدراج الفرص التي تتجاوز الـ 5 ملايين ريال فقط في أجندة رفع التوصيات | Board Memo, Capital Allocation Heatmap | HitL decision latency, Strategy-to-execution compression | BOD / CEO | شهري/فوري للإنذار | 🛑 جميع قرارات تخصيص رأس المال | + +--- + +## 🔍 The Universal Output Contract (متعاقد المخرجات الإلزامي لكل وكيل) + +يجب على كل وكيل في أي مهمة يُخرج فيها قرارًا أو تقريرًا، أن يلتزم بهذا الهيكل الموحّد (Decision Memo JSON): + +```json +{ + "objective": "الهدف الأساسي", + "decision_context": "السياق والحدث الذي استدعى هذه المذكرة", + "inputs_used": ["البيانات والمصادر التي تم تقييمها"], + "assumptions": ["الافتراضات المالية أو التشغيلية المبني عليها التقييم"], + "recommendation_ar": "التوصية المباشرة (ماذا يجب أن نفعل؟)", + "alternatives_considered": ["الخيارات البديلة التي رُفضت ولماذا"], + "expected_financial_impact": { + "revenue_upside_sar": 0, + "cost_downside_sar": 0, + "capital_at_risk_sar": 0 + }, + "risk_register_json": [{"risk": "...", "severity": "...", "mitigation": "..."}], + "confidence_score": 92.5, + "required_approvals": ["CEO", "Compliance"], + "next_best_action": "ما هي الخطوة الفورية القادمة؟", + "rollback_plan": "كيف نتراجع لو أخطأنا؟", + "audit_metadata": { + "agent_id": "alliance_structuring", + "timestamp": "2026-04-16T12:00:00Z", + "policy_check_passed": true + } +} +``` diff --git a/GitHub_Delivery_Pack.md b/GitHub_Delivery_Pack.md new file mode 100644 index 00000000..43c3bf4b --- /dev/null +++ b/GitHub_Delivery_Pack.md @@ -0,0 +1,67 @@ +# Dealix Sovereign Growth OS: GitHub Delivery Pack & Governance Playbook + +هذا المستند وحزمة الملفات المرفقة التي تم إنشاؤها (`.github/` و `docs/adr/`) تضمن أن فريق الهندسة يعمل بمعايير (Enterprise Grade) تحمي النظام من الأخطاء التكتيكية وتحفظ استقرار الـ 8 طبقات تشغيلية. + +--- + +## 1. 🛡️ سياسة الفروع والحماية (Branching & Protection Rules) + +يجب ضبط هذه القواعد فوراً على خوادم GitHub الخاصة بـ Dealix لمنع حدوث "Silent Failures" في طبقة الـ Autonomous Agents. + +### فروع المستودع (Repo Branches) +- `main`: (Production) محمي تماماً. يمنع الـ Push المباشر. +- `staging`: بيئة اختبار لـ QA ومحاكاة الوكلاء. +- `release/*`: للإصدارات المستقرة للمشروع. +- `feature/*`: لأي وكيل جديد، أو سياسة جديدة، أو أداة تفاعل. +- `hotfix/*`: لمعالجة الأعطال الحرجة في الإنتاج. + +### قواعد حماية `main` الإلزامية (Required Rules) +1. **Require Pull Request reviews**: مراجعة واحدة (يفضل 2 للوكلاء الماليين). +2. **Require status checks to pass**: + - `lint / type check` + - `unit tests` + - `policy validation tests` (لضمان أن التعديل لا يخترق الحوكمة). +3. **Require signed commits**: لضمان أمان ومصدر الشفرة. +4. **Do not allow bypassing the above settings**: لا يُسمح بتجاوز هذه القواعد أو إيقافها، حتى للإدمن. + +--- + +## 2. 🗓️ خريطة الـ 90 يوم للتشغيل الفعلي (The 90-Day Execution Backlog) + +### Sprint 1-2 (أسابيع 1 إلى 2): وضع حجر الأساس (Governance & Baseline) +- [ ] إقرار `GitHub governance` + `branch protection` رسمياً. +- [ ] بناء وتوحيد `Event Schema v2.0` لكافة النواحي (Sales, M&A, Growth). +- [ ] تجهيز قوالب المذكرات `Decision Memo Template` ومراجعتها قانونياً. +- [ ] تحديث `router.py` لاعتماد `State Machine Engine` للوكلاء. +- [ ] إنشاء `Entity Graph` الأولي لربط الشركات والفرص والصفقات في قاعدة البيانات. + +### Sprint 3-4 (أسابيع 3 إلى 4): الذكاء الأولي (Early Intel & MVP) +- [ ] إطلاق **Partnership Scout Agent MVP** لقراءة إشارات السوق الحقيقية واستخراج 10 شركاء مستهدفين. +- [ ] إطلاق **Strategic PMO Agent MVP** لربط الفرص بمهام (Jira/Asana). +- [ ] تفعيل **Lead Intelligence Agent** وتقسيم الحسابات آلياً. +- [ ] بناء النسخة الأولى من `Sovereign Dashboard` للمدراء. + +### Sprint 5-6 (أسابيع 5 إلى 6): التحالفات والتوسع (Alliances & Expansion) +- [ ] إطلاق **Alliance Structuring Agent** لبناء نماذج ROI فعلية. +- [ ] تفعيل **Expansion Playbook Agent** لدراسات الدخول للأسواق الجديدة. +- [ ] ربط نظام الحوكمة التلقائي لفرز عمليات `HITL` (إلزامية التدخل الإداري للترم شيتس). +- [ ] التشغيل الداخلي التجريبي (Dogfooding) للوكلاء على بيانات قديمة لـ Dealix. + +### Sprint 7-8 (أسابيع 7 إلى 8): إطلاق منصة الـ M&A +- [ ] بناء وتشغيل **M&A Target Screener** وتوصيله بمصادر القطاع المالي. +- [ ] بناء وتدريب **DD Analyst Agent** لاستخراج وتحليل بيانات غرفة المعطيات الافتراضية (VDR). +- [ ] تطبيق أنظمة الـ Access Control الصارمة جداً على تقارير الـ Board. +- [ ] محاكاة دورة M&A استراتيجية من الصفر للنهاية كاختبار تكامل. + +### Sprint 9-10 (أسابيع 9 إلى 10): التفاوض وبدء حلقة التعلم +- [ ] إطلاق **Valuation & Synergy Agent** و **Executive Negotiator Agent**. +- [ ] بناء محرك `Forecast Vs Actual` لبدء تعديل دقة التوقعات للوكلاء بناءً عن نتائجهم. +- [ ] الإطلاق التدريجي في بيئة الإنتاج (Production) بتفعيل ميزة `Shadow Mode` للـ M&A Agents. +- [ ] تخريج النظام رسمياً كـ Active Sovereign OS وتشغيله الحقيقي. + +--- +**📂 تمت إضافة الملفات التالية للمشروع آلياً:** +- `.github/PULL_REQUEST_TEMPLATE.md` +- `.github/ISSUE_TEMPLATE/agent_feature_request.md` +- `.github/ISSUE_TEMPLATE/governance_policy_update.md` +- `docs/adr/0000-adr-template.md`