@tera-system/pro 0.1.0

package/core/tera-system/AGENT_ACTIVATION_MATRIX.md

@@ -0,0 +1,285 @@
+# AGENT_ACTIVATION_MATRIX.md
+
+# مصفوفة تفعيل العملاء الفرعيين — Sub-Agent Activation Matrix
+
+هذا الملف يحدد **متى يتم تفعيل كل عميل فرعي** في منظومة Tera، ومتى **لا** يتم تفعيله.
+
+---
+
+## القاعدة الحاكمة
+
+> **لا يتم تفعيل العميل لأنه موجود، بل لأنه مطلوب بسبب Trigger واضح.**
+
+**مالك التفعيل حسب المرحلة (SCP-2026-07-28-118):**
+- **Phases 1–4 (Preparation):** مُهندس (ApplicationBlueprintAgent) هو المسؤول عن تفعيل عملاء التحضير والبحث.
+- **Phases 5–7 (Execution):** TeraAgent هو المسؤول عن تفعيل عملاء التنفيذ والتدقيق.
+- العميل لا يُفعّل نفسه ولا يُفعّل عملاء آخرين.
+
+استثناء محدود: `Monitor` يستطيع استدعاء `Auditor` فقط عندما يطلب Majed من Monitor مراجعة/تحدي عمل Tera بجودة مستقلة.
+
+---
+
+## 1. أنواع Triggers
+
+| نوع Trigger | وصف | مثال |
+|---|---|---|
+| `PHASE_GATE` | بداية مرحلة معينة | Phase 4 → Preparation, Phase 6 → Implementation |
+| `DOCUMENT_READY` | وجود ملف معين جاهز | `03_MODULES_AND_FEATURES.md` معتمد → DataDesignAgent |
+| `DECISION_MADE` | قرار من Tera أو المستخدم | "نحتاج تكامل API خارجي" → IntegrationAgent |
+| `COMPLEXITY_SIGNAL` | مؤشر تعقيد | حجم بيانات كبير → PerformanceAgent |
+| `RISK_SIGNAL` | مؤشر خطر | بيانات حساسة → SecurityAgent |
+| `USER_REQUEST` | طلب مباشر من المستخدم | "أضف Domain Research" → DomainResearchAgent |
+| `EXTERNAL_FACTOR` | عامل خارجي | مشروع عميل خارجي → Client Engagement Agents |
+| `REVIEW_NEEDED` | حاجة مراجعة | بعد عدة مهام تنفيذية → QualityReviewCoordinatorAgent |
+| `TASK_COMPLETED` | اكتمال مهمة تنفيذية تحتاج مراجعة بعد التنفيذ | TASK-COD حساس اكتمل → Auditor |
+| `QUALITY_SIGNAL` | ظهور مؤشر جودة أو أثر معماري يحتاج تدقيق | تعقيد/اختبارات ناقصة/تضخم diff → Auditor |
+| `PHASE_7_GATE` | بداية Phase 7 | QAAndAcceptanceAgent + DocumentationHandoverAgent |
+
+---
+
+## 2. مصفوفة التفعيل حسب العميل
+
+### 2.1 العملاء الأساسيون
+
+| العميل | المعرف | Trigger التفعيل | المرحلة | متى لا يُفعّل | الحد الأدنى من المدخلات |
+|---|---|---|---|---|---|
+| RequirementsScopeAgent | `REQ_SCOPE_AGENT` | `DOCUMENT_READY`: بعد `TERA_PROJECT_DECISION.md` أو `00_PROJECT_INPUTS.md` | 2–3 | إذا كانت الفكرة بسيطة وواضحة بالكامل ويمكن لـ Tera كتابة `01_PROJECT_BRIEF.md` مباشرة | `00_PROJECT_INPUTS.md` أو `TERA_PROJECT_DECISION.md` |
+| BusinessWorkflowAgent | `BUSINESS_WORKFLOW_AGENT` | `DOCUMENT_READY`: بعد اعتماد `01_PROJECT_BRIEF.md` + `02_SCOPE_AND_BOUNDARIES.md` + وجود workflows | 3–4 | إذا كان التطبيق لا يحتوي أي دورة عمل أو حالات (مثل CRUD بسيط بدون موافقات) | `01_PROJECT_BRIEF.md` + `02_SCOPE_AND_BOUNDARIES.md` |
+| UIUXStructureAgent | `UI_UX_STRUCTURE_AGENT` | `DOCUMENT_READY`: بعد اعتماد الموديولات ومسارات العمل | 4 | إذا كان المشروع API-only أو Backend-only بدون واجهة مستخدم | `03_MODULES_AND_FEATURES.md` + `05_BUSINESS_WORKFLOWS.md` |
+| UIVisualDesignerAgent | `UI_VISUAL_DESIGNER_AGENT` | `COMPLEXITY_SIGNAL`: وجود Frontend مهم أو مصدر تصميم (Figma, getdesign.md, screenshots) | 4–5 | إذا كان المشروع API-only، أو UI بسيط جدًا بدون متطلبات بصرية | `07_SCREENS_AND_UI_STRUCTURE.md` + مصدر التصميم |
+| DataDesignAgent | `DATA_DESIGN_AGENT` | `DOCUMENT_READY`: بعد وضوح الموديولات والعمليات | 4 | إذا كان التطبيق لا يملك بيانات مترابطة (مثل موقع بسيط بمحتوى ثابت) | `03_MODULES_AND_FEATURES.md` + `05_BUSINESS_WORKFLOWS.md` |
+| SolutionArchitectureAgent | `SOLUTION_ARCH_AGENT` | `PHASE_GATE`: قبل التنفيذ (Phase 5) | 5 | إذا كان المشروع صغيرًا جدًا والتقنيات محددة مسبقًا بدون قرارات معمارية مؤثرة | `08_TECHNICAL_ARCHITECTURE.md` أو `00_PROJECT_INPUTS.md` |
+| EngineeringAgent (Fallback) | `ENGINEERING_AGENT` | `PHASE_GATE`: عند وجود مهمة تنفيذية مع `Pre-Execution Gate: PASS` وليس للـ stack وكيل متخصص | 6 | يُفضّل تفعيل الوكيل المتخصص أولاً. لا يُفعّل بدون `TASK-COD-*` معتمد. لا يُفعّل لتحضير أو تحليل | ملفات التحليل والتصميم المعتمدة + `TASK-ID` + `Pre-Execution Gate: PASS` |
+| EngineeringAgentTypeScript | `ENGINEERING_AGENT_TS` | `PHASE_GATE`: عند وجود مهمة TypeScript/Node.js functional code مع `Pre-Execution Gate: PASS` | 6 | لا يُفعّل لمهام .NET/C# (وجّه لـ dotnet). لا يُفعّل لمهام Phaser (وجّه لـ phaser). لا يُفعّل لمهام UI البصرية (وجّه لـ ui-designer) | ملفات التحليل والتصميم المعتمدة + `TASK-ID` + `Pre-Execution Gate: PASS` + Active Technology Profile |
+| EngineeringAgentPhaser | `ENGINEERING_AGENT_PHASER` | `PHASE_GATE`: عند وجود مهمة Phaser 3 game engine مع `Pre-Execution Gate: PASS` | 6 | لا يُفعّل لمهام React/Backend (وجّه لـ typescript). لا يُفعّل لمهام .NET/C# | ملفات التحليل والتصميم المعتمدة + `TASK-ID` + `Pre-Execution Gate: PASS` + Game Design Documents |
+| QAAndAcceptanceAgent | `QA_ACCEPTANCE_AGENT` | **Planning Mode:** `PHASE_GATE` + `DOCUMENT_READY`: قبل إعداد خطة التنفيذ. **Execution Mode:** `DOCUMENT_READY`: بعد تنفيذ `TASK-COD-*` يحتاج تحقق فعلي (build/test/run/connect). **كلا الوضعين:** قبل Phase 7 وقبل قبول أي مرحلة | 5–6–7 | **Planning Mode:** إذا كانت المهمة بسيطة ومعايير القبول واضحة ويمكن لـ Tera كتابتها مباشرة. **Execution Mode:** إذا كانت المهمة لا تحتاج اختبار CLI (مثل وثائق أو تحضير) | `10_TESTING_AND_ACCEPTANCE.md` (Planning) أو ملف `TASK-COD-*` المنفذ + معايير القبول (Execution) |
+| Auditor | `AUDITOR` | `TASK_COMPLETED` + `RISK_SIGNAL` / `QUALITY_SIGNAL` / `REVIEW_NEEDED`: بعد مهمة تنفيذية ذات مخاطرة أو أثر جودة؛ ويستدعيه Monitor فقط بطلب Majed | 6 | إذا كانت المهمة وثائقية أو صغيرة منخفضة المخاطر وقرار Tera هو `AUDITOR_REVIEW_NOT_REQUIRED` مع سبب موثق | ملف المهمة + Handback + diff/changed files + QA/Security/analyzer evidence عند وجودها + `QUALITY_GATE_THRESHOLDS.md` |
+| DocumentationHandoverAgent | `DOC_HANDOVER_AGENT` | `PHASE_7_GATE`: عند قرب التسليم أو في Phase 7 | 7 | إذا كان المشروع داخليًا small ولن يُسلّم لطرف آخر | ملفات التحليل والتصميم المعتمدة |
+
+---
+
+### 2.2 العملاء المشروطون
+
+| العميل | المعرف | Trigger التفعيل | المرحلة | متى لا يُفعّل | الحد الأدنى من المدخلات |
+|---|---|---|---|---|---|
+| SecurityAgent | `SECURITY_AGENT` | `RISK_SIGNAL`: بيانات حساسة، Auth، صلاحيات مدفوعات، أسرار، Middleware، Config حرجة | 5–6–7 | إذا لم يكن هناك أي بيانات حساسة أو صلاحيات أو تكاملات خارجية | `04_USERS_ROLES_PERMISSIONS.md` + `08_TECHNICAL_ARCHITECTURE.md` |
+| IntegrationAgent | `INTEGRATION_AGENT` | `EXTERNAL_FACTOR`: API خارجي، بوابة دفع، Webhooks، ERP خارجي | 5–6 | إذا كان المشروع لا يتصل بأي خدمة خارجية | `14_INTEGRATIONS_AND_EXTERNAL_SERVICES.md` أو ما يعادلها |
+| DevOpsDeploymentAgent | `DEVOPS_DEPLOYMENT_AGENT` | `EXTERNAL_FACTOR / USER_REQUEST`: نشر فعلي، CI/CD، Docker، Cloud، Domain/SSL | 6–7 | إذا كان المشروع في بيئة محلية فقط أو لا يحتاج نشر رسمي بعد | `22_DEPLOYMENT_AND_ENVIRONMENTS.md` أو `08_TECHNICAL_ARCHITECTURE.md` |
+| PerformanceAgent | `PERFORMANCE_AGENT` | `COMPLEXITY_SIGNAL`: حجم بيانات كبير، مستخدمون كثر، SLA، بطء متوقع | 5–6 | إذا كان المشروع صغيرًا وعدد المستخدمين محدودًا | `06_DATA_MODEL_PREPARATION.md` + `32_PERFORMANCE_REQUIREMENTS.md` |
+| ComplianceAgent | `COMPLIANCE_AGENT` | `RISK_SIGNAL`: متطلبات قانونية، بيانات شخصية، مالية، قطاع منظم | 5–6–7 | إذا لم يكن المشروع خاضعًا لأي تنظيم أو امتثال | `34_COMPLIANCE_AND_LEGAL_NOTES.md` أو `02_SCOPE_AND_BOUNDARIES.md` |
+| ReportingAnalyticsAgent | `REPORTING_ANALYTICS_AGENT` | `COMPLEXITY_SIGNAL`: تقارير كثيرة، Dashboard، KPIs، تصدير | 5–6 | إذا كان التطبيق لا يحتوي تقارير أو لوحات بيانات | `13_REPORTS_AND_DASHBOARDS.md` |
+| MaintenanceMigrationAgent | `MAINTENANCE_MIGRATION_AGENT` | `EXTERNAL_FACTOR`: نظام قائم، ترحيل بيانات، Legacy | 5–6–7 | إذا كان المشروع جديدًا بالكامل بدون ترحيل | `31_MAINTENANCE_AND_SUPPORT.md` أو `00_PROJECT_INPUTS.md` |
+| ProjectControlAgent | `PROJECT_CONTROL_AGENT` | `REVIEW_NEEDED`: عند الحاجة لتحديث سجلات `project-control` أو فحص اتساق | 4–5–6–7 | إذا لم تكن هناك حاجة لتحديث سجلات متعددة أو فحص اتساق | ملفات project-control الحالية |
+| SoftwareDesignerAgent | `SOFTWARE_DESIGNER_AGENT` | `COMPLEXITY_SIGNAL`: مهمة متعددة العملاء، أو تتجاوز 3 ملفات، أو تحمل مخاطر، أو تحتاج Technical Specification | 5–6 | إذا كانت المهمة بسيطة ويمكن لـ Tera تجهيز Technical Specification مباشرة | ملفات التحليل المعتمدة + `TECHNICAL_SPECIFICATION.md` |
+| QualityReviewCoordinatorAgent | `QUALITY_REVIEW_COORDINATOR_AGENT` | `REVIEW_NEEDED`: قبل مرحلة تنفيذ كبيرة، أو بعد عدة مهام، أو قبل Release | 5–6–7 | إذا كان المشروع صغيرًا والمهام قليلة ويمكن لـ Tera متابعتها يدويًا | `PROJECT_STATE.md` + `TASK_REGISTRY.md` |
+| PlanComplianceReviewAgent | `PLAN_COMPLIANCE_REVIEW_AGENT` | `REVIEW_NEEDED`: نهاية Phase، أو بعد دفعة مهام رئيسية، أو قبل قبول MVP | 5–6–7 | إذا كان التنفيذ متوافقًا بوضوح مع الخطة ولا توجد انحرافات ظاهرة | `PROJECT_MASTER_PLAN.md` + `TASK_REGISTRY.md` |
+| DomainResearchAgent | `DOMAIN_RESEARCH_AGENT` | `COMPLEXITY_SIGNAL / USER_REQUEST`: مجال غير مألوف، أو حاجة بحث خارجي | 1–2–3 | إذا كان المجال معروفًا بالكامل أو المستخدم قدم جميع المعلومات المطلوبة | Domain Research Brief من Tera |
+| DomainExpertAgent | `DOMAIN_EXPERT_AGENT` | `COMPLEXITY_SIGNAL`: بعد اكتمال Domain Research، أو عند الحاجة لتحليل متقدم | 2–3–4 | إذا لم يُظهر Domain Research نتائج تستدعي تحليلًا إضافيًا | Domain Research Report + Domain Research Brief |
+| ProductionERPExpert | `PRODUCTION_ERP_EXPERT` | `COMPLEXITY_SIGNAL / USER_REQUEST`: موديول تصنيع/إنتاج ERP، أو حاجة لتحليل BOM/Routing/MRP/WIP/Costing/Quality/Rework/Scrap أو مراجعة Production Blueprint | 1–5 | إذا كان المشروع لا يحتوي تصنيع/إنتاج، أو كانت الأسئلة CRUD عامة لا تحتاج خبرة Production ERP | Production context + ملفات discovery/blueprint ذات الصلة + KB index عند الحاجة |
+
+---
+
+### 2.3 عملاء التعامل مع العملاء الخارجيين
+
+| العميل | المعرف | Trigger التفعيل | المرحلة | متى لا يُفعّل | الحد الأدنى من المدخلات |
+|---|---|---|---|---|---|
+| ClientDiscoveryAgent | `CLIENT_DISCOVERY_AGENT` | `EXTERNAL_FACTOR`: بداية مشروع عميل خارجي | Client Discovery (قبل Phase 1) | إذا كان المشروع داخليًا (غير موجه لعميل خارجي) | `CLIENT_PROFILE.md` + `project-inputs/` |
+| ProposalScopeAgent | `PROPOSAL_SCOPE_AGENT` | `EXTERNAL_FACTOR`: بعد اكتمال Client Discovery واعتماد الفهم | Client Discovery (قبل Phase 1) | إذا لم يكتمل Client Discovery بعد | `project-inputs/` كاملة |
+| ClientApprovalReviewAgent | `CLIENT_APPROVAL_REVIEW_AGENT` | `EXTERNAL_FACTOR`: قبل إرسال حزمة اعتماد العميل أو قبل Build Mode | ما قبل التنفيذ | إذا لم تكتمل حزمة الاعتماد بعد | `clients/.../client-approval/` |
+| ChangeControlAgent | `CHANGE_CONTROL_AGENT` | `EXTERNAL_FACTOR`: طلب تغيير جديد بعد اعتماد النطاق | أي مرحلة بعد اعتماد النطاق | إذا لم يظهر أي طلب تغيير | `11_CHANGE_CONTROL.md` أو طلب التغيير الجديد |
+
+---
+
+## 3. مصفوفة التفعيل حسب نوع المشروع
+
+### 3.1 مشروع صغير (CRUD بسيط)
+
+| العميل | هل يُفعّل؟ | ملاحظة |
+|---|---|---|
+| RequirementsScopeAgent | اختياري | إذا كانت الفكرة بسيطة وواضحة، يمكن لـ Tera كتابة `01_PROJECT_BRIEF.md` مباشرة |
+| BusinessWorkflowAgent | لا | إذا لم يكن هناك workflows |
+| UIUXStructureAgent | اختياري | إذا كان هناك واجهة بسيطة |
+| UIVisualDesignerAgent | لا | إلا إذا قدم المستخدم ألوانًا أو مصدر تصميم |
+| DataDesignAgent | اختياري | إذا كانت البيانات مترابطة |
+| SolutionArchitectureAgent | لا | التقنيات محددة مسبقًا |
+| EngineeringAgent | نعم | مع `Pre-Execution Gate: PASS` |
+| QAAndAcceptanceAgent | اختياري | يمكن لـ Tera مراجعة المهمة مباشرة |
+| DocumentationHandoverAgent | لا | |
+| SecurityAgent | لا | إلا إذا كان هناك Auth |
+| باقي المشروطون | لا | لا triggers كافية |
+
+### 3.2 مشروع متوسط (تطبيق ويب متكامل مع Dashboard)
+
+| العميل | هل يُفعّل؟ | ملاحظة |
+|---|---|---|
+| RequirementsScopeAgent | نعم | |
+| BusinessWorkflowAgent | نعم | إذا كان هناك workflows |
+| UIUXStructureAgent | نعم | |
+| UIVisualDesignerAgent | اختياري | إذا كان هناك متطلبات بصرية |
+| DataDesignAgent | نعم | |
+| SolutionArchitectureAgent | نعم | |
+| EngineeringAgent | نعم | |
+| QAAndAcceptanceAgent | نعم | |
+| DocumentationHandoverAgent | اختياري | إذا كان هناك تسليم لطرف آخر |
+| SecurityAgent | نعم | إذا كان هناك Auth أو صلاحيات |
+| PerformanceAgent | اختياري | إذا توقعنا حجم مستخدمين متوسط |
+| ReportingAnalyticsAgent | اختياري | إذا كان هناك Dashboard |
+| ProjectControlAgent | اختياري | عند تعدد المهمات |
+| SoftwareDesignerAgent | اختياري | عند تعقيد المهمات |
+| Auditor | اختياري | مطلوب فقط عند risk/architecture/quality trigger بعد التنفيذ |
+
+### 3.3 مشروع ERP (نظام تخطيط موارد مؤسسة)
+
+| العميل | هل يُفعّل؟ | ملاحظة |
+|---|---|---|
+| RequirementsScopeAgent | نعم | |
+| BusinessWorkflowAgent | نعم | أساسي في ERP |
+| UIUXStructureAgent | نعم | |
+| UIVisualDesignerAgent | نعم | إذا كان UI مهمًا |
+| DataDesignAgent | نعم | أساسي |
+| SolutionArchitectureAgent | نعم | |
+| EngineeringAgent | نعم | مع تفعيل متكرر عبر موديولات متعددة |
+| QAAndAcceptanceAgent | نعم | |
+| DocumentationHandoverAgent | نعم | ERP يحتاج توثيق تسليم كامل |
+| SecurityAgent | نعم | ERP يحتوي صلاحيات وبيانات حساسة |
+| IntegrationAgent | نعم | تكاملات خارجية متوقعة |
+| DevOpsDeploymentAgent | نعم | نشر في بيئات متعددة |
+| PerformanceAgent | نعم | حجم بيانات كبير |
+| ComplianceAgent | اختياري | حسب المجال |
+| ReportingAnalyticsAgent | نعم | ERP يحتوي تقارير كثيرة |
+| MaintenanceMigrationAgent | نعم | ERP يحتاج ترحيل بيانات |
+| ProjectControlAgent | نعم | إدارة تتبع متقدمة |
+| SoftwareDesignerAgent | نعم | مهام متعددة ومعقدة تحتاج Technical Specification |
+| QualityReviewCoordinatorAgent | نعم | بعد مجموعات مهام |
+| Auditor | نعم | بعد المهام الحساسة أو ذات الأثر المعماري/الجودة |
+| PlanComplianceReviewAgent | نعم | قبل قبول مراحل |
+| DomainResearchAgent | اختياري | لمجالات ERP غير المألوفة |
+| DomainExpertAgent | اختياري | لتحليل متقدم للمجال |
+| ProductionERPExpert | نعم عند وجود موديول تصنيع/إنتاج | أساسي لمشاريع ERP التصنيعية أو أي Production module |
+| Client Engagement Agents | اختياري | إذا كان ERP لعميل خارجي |
+
+### 3.4 مشروع SaaS (منصة خدمية)
+
+| العميل | هل يُفعّل؟ | ملاحظة |
+|---|---|---|
+| RequirementsScopeAgent | نعم | |
+| BusinessWorkflowAgent | نعم | |
+| UIUXStructureAgent | نعم | |
+| UIVisualDesignerAgent | نعم | UI مهم لـ SaaS |
+| DataDesignAgent | نعم | |
+| SolutionArchitectureAgent | نعم | |
+| EngineeringAgent | نعم | |
+| QAAndAcceptanceAgent | نعم | |
+| DocumentationHandoverAgent | نعم | توثيق للمستخدمين |
+| SecurityAgent | نعم | Auth/Multi-tenant أساسي |
+| IntegrationAgent | اختياري | حسب التكاملات |
+| DevOpsDeploymentAgent | نعم | نشر مستمر |
+| PerformanceAgent | نعم | قابلية التوسع |
+| ReportingAnalyticsAgent | اختياري | حسب الاحتياج |
+| ProjectControlAgent | اختياري | عند تعدد المهمات |
+| SoftwareDesignerAgent | اختياري | عند تعقيد المهمات |
+
+---
+
+## 4. قواعد التفعيل الصارمة
+
+### 4.1 لا تفعيل تلقائي للعملاء
+
+```
+تفعيل العميل يتم بقرار من Tera فقط، استنادًا إلى Trigger واضح.
+الاستثناء الوحيد في v1: Monitor → Auditor بطلب Majed الصريح.
+لا يتم تفعيل العميل تلقائيًا لمجرد دخول مرحلة أو وجود ملف جاهز.
+```
+
+### 4.2 لا تفعيل بدون مدخلات كافية
+
+```
+لا يُفعّل عميل إذا لم تتوفر المدخلات الدنيا المطلوبة.
+إذا كانت المدخلات ناقصة، إما:
+  - أن يكمل Tera المدخلات بنفسه
+  - أو يُفعّل عميلًا آخر لتجهيز المدخلات أولاً
+  - أو يطلب من المستخدم إكمالها
+```
+
+### 4.3 لا تفعيل عميل موجود بالفعل في مهمة حاليًا
+
+```
+لا يتم تفعيل نسخة جديدة من عميل موجود حاليًا في مهمة نشطة،
+إلا إذا كان العميل جاهزًا لتسلم مهمة جديدة ومستقلة.
+```
+
+### 4.4 لا تفعيل عميل لمتطلبات مستقبلية
+
+```
+لا يتم تفعيل عميل بناءً على متطلبات أو سيناريوهات قد تحدث في المستقبل.
+التفعيل يكون للحاجة الحالية فقط.
+```
+
+### 4.5 عميل واحد لكل اختصاص في كل مرة
+
+```
+لا يتم تفعيل عميلين لهما نفس الاختصاص (مثل اثنين EngineeringAgent) في وقت واحد
+على نفس الموديول، إلا في حالات المهام المتوازية المستقلة تمامًا.
+```
+
+---
+
+## 5. تسجيل قرار التفعيل
+
+عند تفعيل أي عميل فرعي، يسجل Tera في `PROJECT_ACTIVITY_LOG.md`.
+وعند استدعاء Monitor لـ Auditor بطلب Majed، يسجل Monitor ذلك في تقريره أو في السجل المتاح له:
+
+```
+- Agent ID
+- Activation Trigger
+- Task ID المستهدف
+- المرحلة الحالية
+- Brief reason for activation
+```
+
+---
+
+## 6. إلغاء التفعيل أو التعطيل المؤقت
+
+إذا تم تفعيل عميل ثم تبين أنه غير مطلوب:
+
+1. يتم إنهاء مهمته الحالية بحالة `Cancelled` مع سبب واضح.
+2. يسجل Tera الإلغاء في `PROJECT_ACTIVITY_LOG.md`.
+3. لا يُعاد تفعيله إلا عند ظهور Trigger جديد ومستقل.
+
+---
+
+## 7. أمثلة على تطبيق القواعد
+
+### مثال 1: مشروع ERP جديد — مرحلة التحضير
+
+```
+Trigger: بداية Phase 4 (Preparation)
+مُهندس يقرر: تفعيل RequirementsScopeAgent و BusinessWorkflowAgent و DataDesignAgent
+لا يُفعّل: SolutionArchitectureAgent (يُفعّل لاحقاً في Phase 4 حسب الحاجة)، SecurityAgent (لا يوجد موديول حساس بعد)
+```
+
+### مثال 2: طلب تغيير من عميل
+
+```
+Trigger: طلب إضافة تكامل دفع خارجي
+Tera يقرر: تفعيل IntegrationAgent
+لا يُفعّل: ChangeControlAgent (لأنه سيقترح فقط، ويمكن لـ Tera إدارة ذلك)
+```
+
+### مثال 3: مراجعة بعد 5 مهام تنفيذية
+
+```
+Trigger: REVIEW_NEEDED
+Tera يقرر: تفعيل QualityReviewCoordinatorAgent
+بعد تقريره: قد يُفعّل SecurityAgent إذا وجد findings أمنية
+```
+
+---
+
+## 8. الملخص — قاعدة التفعيل الذهبية
+
+> **عند الشك، لا تُفعّل.**
+>
+> العميل هو أداة متخصصة تُستدعى للحاجة الحالية فقط،
+> وليس عضوا دائمًا في فريق المشروع.

package/core/tera-system/AGENT_DEPENDENCY_MAP.md

@@ -0,0 +1,117 @@
+<!-- © 2026 Majed Khaireddin (Alabasi1980). Tera System — Proprietary. All rights reserved. -->
+
+# AGENT_DEPENDENCY_MAP.md
+
+## الغرض
+خريطة العلاقات بين ملفات العملاء في `.opencode/agents/`. تساعد في:
+- تتبع أثر أي تعديل على عميل — ما الملفات الأخرى التي قد تتأثر
+- كشف المراجع المكسورة بعد التحديثات
+- تحديد ترتيب التعديل الآمن
+
+---
+
+## 🔗 خريطة العلاقات
+
+| Agent | يتم استدعاؤه بواسطة | يستدعي/يشير إلى | يقرأ من |
+|-------|-------------------|----------------|---------|
+| **tera.md** | — (Engineering Delivery Lead — phases 5–7 — SCP-118) | `ui-designer.md`, `engineering-agent.md`, `engineering-agent-typescript.md`, `engineering-agent-phaser.md`, `engineering-agent-dotnet.md`, `tera-software-designer.md`, `auditor.md` | `tera-system/runtime/TERA_RUNTIME_*.md`, `project-control/`, `ENGINEERING_HANDOFF_PACKAGE.md` |
+| **ui-designer.md** | `tera.md`, `tera-system-evolution.md` (للأغراض النظامية) | `design-reviewer.md` (ناقد يراجعه)، `engineering-agent-typescript.md` (يسلّم له UI Spec) | `28_UI_UX_GUIDELINES.md`, `tera-system/design-system/*.md` |
+| **engineering-agent.md** | `tera.md` | `ui-designer.md` (مصمم يسبقه)، `tera-software-designer.md` (يسبقه للمهام المعقدة) | `TECHNICAL_SPECIFICATION.md`, `28_UI_UX_GUIDELINES.md` |
+| **engineering-agent-typescript.md** 🆕 | `tera.md` | `ui-designer.md` (يستلم منه UI Spec)، `engineering-agent-phaser.md` (يملك integration bridge معه) | `engineering-agent-core.md`, Active Technology Profile, `28_UI_UX_GUIDELINES.md` |
+| **engineering-agent-phaser.md** 🆕 | `tera.md` | `engineering-agent-typescript.md` (يملك bridge معه عبر Tera) | `engineering-agent-core.md`, Active Technology Profile, game design documents |
+| **engineering-agent-dotnet.md** | `tera.md` | — | `engineering-agent-core.md`, Active .NET Technology Profile |
+| **tera-software-designer.md** | `tera.md` | `engineering-agent.md` (ينفذ الـ Spec) | `project-preparation/*.md`, `28_UI_UX_GUIDELINES.md`, `PROJECT_RULES.md` |
+| **design-reviewer.md** | — (مستقل — يستدعيه Majed) | `TeraAgent`, `EngineeringAgent` (مراجعة مخرجاتهم) | `28_UI_UX_GUIDELINES.md`, `tera-system/design-system/DESIGN_REVIEW_STANDARDS.md` |
+| **tera-client-engagement.md** | — (مستقل — يستدعيه Majed) | `domain-research-agent.md`, `domain-expert-agent.md`, `production-erp-expert.md`, `application-blueprint.md` | `tera-system/client-helpers/*.md`, `tera-system/TeraPricingPolicy.md` |
+| **application-blueprint.md** | `tera-client-engagement.md` (handoff); — (Solution Preparation Authority — phases 1–4 — SCP-118) | `domain-research-agent.md`, `domain-expert-agent.md`, `production-erp-expert.md`, preparation agents, `qa-agent.md` (Planning Mode), `ui-designer.md` (Preparation Design Mode) | `tera-system/runtime/TERA_SOLUTION_PREPARATION_*.md`, `project-preparation/`, `client-engagement/` |
+| **domain-research-agent.md** | `tera-client-engagement.md`, `tera.md`, `application-blueprint.md`, `tera-system-evolution.md` | `domain-expert-agent.md` (يسلم له للتحليل) | — (بحث خارجي) |
+| **domain-expert-agent.md** | `tera-client-engagement.md`, `tera.md`, `application-blueprint.md`, `tera-system-evolution.md` | — | `domain-research-agent.md` (Domain Research Report) |
+| **production-erp-expert.md** | Majed مباشرة، `tera.md`, `tera-client-engagement.md`, `application-blueprint.md`؛ وEngineering/QA فقط عبر Tera-approved task scope | `domain-research-agent.md` عند نقص المعرفة وبقرار المستدعي | `tera-system/knowledge-base/manufacturing/`, ملفات discovery/blueprint المحددة |
+| **tera-system-evolution.md** | — (مستقل — يستدعيه Majed) | `ui-designer.md`, `domain-research-agent.md`, `domain-expert-agent.md` (للأغراض النظامية) | `tera-system/*.md`, `.opencode/agents/*.md` |
+| **tera-strategic-advisor.md** | — (مستقل — يستدعيه Majed فقط) | لا يستدعي عملاء ولا يديرهم؛ قد يوصي Majed بالرجوع إلى TeraAgent أو حارس أو غيرهم | ملفات وسياقات القرار فقط، مصادر خارجية عند الحاجة |
+| **auditor.md** | `tera.md`؛ و`monitor.md` فقط عند طلب Majed | يراجع مخرجات `tera.md`, `engineering-agent.md`؛ يحيل findings إلى `SecurityAgent`, `DesignReviewer`, `QAAndAcceptanceAgent`, أو `ProjectControlAgent` عبر الوكيل المستدعي | `project-control/*.md`, `project-control/audit-reports/`, `tera-system/engineering-governance/*.md`, الملفات المعدلة |
+| **monitor.md** | — (مستقل — يستدعيه Majed) | يراجع مخرجات `tera.md`, `engineering-agent.md`; قد يستدعي `auditor.md` فقط عندما يطلب Majed تحدي/تحقق جودة مستقل | `project-control/*.md`, `tera-system/*.md` |
+| **qa-agent.md** (الاسم المنطقي: QAAndAcceptanceAgent) | `tera.md` (يُفعّله Tera) | لا يستدعي عملاء آخرين | ملفات التحضير، ملفات المهمة، logs، مخرجات CLI، `project-control/test-reports/` |
+| **tera-business-transformation-consultant.md** | — (مستقل — يُستدعى من TCEA عبر Majed عند Track C) | `domain-research-agent.md`, `domain-expert-agent.md` (للبحث عن معايير الصناعة وأفضل الممارسات) | `tera-system/consulting-helpers/BTCA_METHODOLOGY_FRAMEWORK.md`, `BTCA_REPORT_TEMPLATES.md` |
+
+---
+
+## 📏 ترتيب التعديل الآمن
+
+عند تعديل أي Agent، اتبع هذا التسلسل لتجنب كسر المراجع:
+
+```
+1. غيّر الملف الأساسي
+2. راجع AGENT_DEPENDENCY_MAP.md — من يشير لهذا الملف؟
+3. افتح كل ملف يشير إليه وتحقق من أن المراجع ما زالت صحيحة
+4. إذا وجدت مرجعاً مكسوراً → صححه
+5. سجل التغيير
+```
+
+### مثال: تعديل `ui-designer.md`
+```
+ui-designer.md
+  ↑ يشير إليه: tera.md (Section 8 — يستدعيه)
+  ↑ يشير إليه: design-reviewer.md (Section 11 — يقارن نفسه به)
+  ↑ يشير إليه: engineering-agent.md (Section 3 — يتكامل معه)
+  ↑ يشير إليه: tera-system-evolution.md (Section 7.1 — يستدعيه لأغراض نظامية)
+
+يجب فتح: tera.md + design-reviewer.md + engineering-agent.md + tera-system-evolution.md
+وتأكيد أن الإشارات ما زالت صحيحة بعد التعديل.
+```
+
+---
+
+## ⚠️ تنبيهات حجم الملف
+
+الجدول أدناه يستخدم القاعدة المحدّثة: < 700 = ✅, 700–1000 = 🟡 دراسة, > 1000 = 🔴 تقسيم إجباري.
+
+| الملف | الحجم (سطور) | الحالة / ملاحظات |
+|-------|-------------|-----------------|
+| `tera.md` | 520 | 🟢 < 700 — +4 (SCP-2026-08-16-003: READY FOR OWNER ACCEPTANCE §12) |
+| `tera-system/TeraSubAgents.md` | 855 | 🟡 700–1000 — يحتاج دراسة تقسيم قريبة |
+| `tera-system/TeraHelperAgents.md` | 970 | 🟡 700–1000 — يحتاج دراسة تقسيم قريبة |
+| `tera-system/runtime/TERA_RUNTIME_TEMPLATES.md` | 908 | 🟡 700–1000 — +5 (SCP-2026-08-16-001: ملاحظة تفويض المدققين §2) — تقسيم مكتمل سابقاً (INS-02) |
+| `tera-system/runtime/TERA_RUNTIME_TEMPLATES_DELIVERY.md` | 514 | 🟢 < 700 — +9 (SCP-2026-08-16-003: §32 Owner Approval fields + §33 items 10–11) |
+| `tera-system/runtime/TERA_RUNTIME_TEMPLATES_PREPARATION.md` | 344 | 🟢 < 700 — جديد INS-02 (§35–40) |
+| `tera-system/runtime/TERA_RUNTIME_PROTOCOLS.md` | 50 | 🟢 < 700 — §19 فقط (Knowledge Management) بعد تقسيم INS-02 continuation |
+| `tera-system/runtime/TERA_RUNTIME_PROTOCOLS_CORE.md` | 799 | 🟡 700–1000 — +31 (SCP-2026-08-16-003: Owner Approval Gate + Cross-Record Consistency §4) — قريب من الحد — مراقبة |
+| `tera-system/runtime/TERA_RUNTIME_PROTOCOLS_CLIENT.md` | 356 | 🟢 < 700 — جديد INS-02 (§12–18) |
+| `tera-system/runtime/TERA_RUNTIME_CHECKLISTS.md` | 646 | 🟢 < 700 — +1 (SCP-2026-08-16-003: Phase 6 بند 8) |
+| `tera-system/TeraPreExecutionGate.md` | 818 | 🟡 700–1000 — +18 (SCP-2026-08-16-003: Owner Approval Gate + Checklist 33–35) |
+| `tera-client-engagement.md` | 892 | 🟡 700–1000 — توسعة Dual-Track عبر SCP-2026-07-29-001 |
+| `auditor.md` | 665 | 🟢 < 700 — +22 (SCP-2026-08-16-001: Independent Scope Discovery §6.1) |
+| `qa-agent.md` | 498 | 🟢 < 700 — +23 (SCP-2026-08-16-001: Independent Discovery §3.1 + NOT VERIFIED) |
+| `tera-system-evolution.md` | 754 | 🟡 700–1000 — قريب من الحد — يحتاج مراقبة |
+| `tera-strategic-advisor.md` | 325 | 🟢 < 700 |
+| `engineering-agent-typescript.md` | 300 | 🟢 < 700 |
+| `engineering-agent-phaser.md` | 275 | 🟢 < 700 |
+| `monitor.md` | 395 | 🟢 < 700 — +117 (SCP-2026-08-16-004: تصنيف + Lifecycle + Quick/Full + Snapshot + قوالب) — يقرأ/يكتب `MONITOR_STATE.md` |
+| `application-blueprint.md` | 407 | 🟢 < 700 — SCP-118 compact redesign + SCP-2026-08-15-016 (شرط Content في §9) |
+| `tera-system/engineering-helpers/engineering-agent-core.md` | 171 | 🟢 — ملف مشارك |
+| `tera-system/client-helpers/tera-client-engagement-protocols.md` | 692 | 🟢 < 700 — +3 بروتوكولات Track B |
+| `tera-system/client-helpers/tera-client-engagement-pricing.md` | 341 | 🟢 < 700 — +Product Pricing Models |
+| `tera-system/client-helpers/tera-client-engagement-gates.md` | 258 | 🟢 < 700 — +6 بوابات Track B + B.7c Final Consistency (SCP-014) |
+| `tera-system/client-helpers/tera-client-engagement-discovery-domains.md` | 98 | 🟢 < 700 — +Existing App + Track B |
+| `tera-system/runtime/TERA_SOLUTION_PREPARATION_PROTOCOL.md` | 279 | 🟢 < 700 — ملف SCP-118 |
+| `tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md` | 397 | 🟢 < 700 — ملف SCP-118 |
+| `.opencode/agents/tera-business-transformation-consultant.md` | 290 | 🟢 < 700 — عميل SCP-2026-07-29-002 |
+| `tera-system/consulting-helpers/BTCA_METHODOLOGY_FRAMEWORK.md` | 195 | 🟢 < 700 — منهجية الأدلة ومراحل العمل |
+| `tera-system/consulting-helpers/BTCA_REPORT_TEMPLATES.md` | 266 | 🟢 < 700 — قوالب التقارير العشرة |
+
+**ملاحظة (تحديث 2026-08-01 — INS-01):** تمت إعادة حساب جميع الأحجام الفعلية وتصحيح الجدول. الملفات 🔴 (>1000) تحتاج خطط تقسيم (انظر INS-02). الملفات 🟡 (700–1000) قيد المراقبة.
+
+---
+
+## 📐 خطة تقسيم الملفات الكبيرة (INS-02 — 2026-08-01)
+
+المبدأ: التقسيم عند الحاجة الحقيقية — ملفات runtime تُقسَّم حسب الوظيفة (كما في استثناءات §"حجم الملف" في تعريف حارس).
+
+| الملف | الحجم | خطة التقسيم المقترحة | الحالة |
+|-------|-------|---------------------|--------|
+| `tera-system/runtime/TERA_RUNTIME_TEMPLATES.md` | 903 | **✅ تم التقسيم (2026-08-01):** §29–34 → `TERA_RUNTIME_TEMPLATES_DELIVERY.md` (505)، §35–40 → `TERA_RUNTIME_TEMPLATES_PREPARATION.md` (344) | ✅ **مكتمل** |
+| `tera-system/runtime/TERA_RUNTIME_PROTOCOLS.md` | 50 | **✅ تم التقسيم (2026-08-01):** §1–11 → `TERA_RUNTIME_PROTOCOLS_CORE.md` (758)، §12–18 → `TERA_RUNTIME_PROTOCOLS_CLIENT.md` (356)، الرئيسي يحتفظ بـ §19 | ✅ **مكتمل** |
+| `tera-system/Tera_Project_Preparation_Files.md` | 1,015 | **قرار (2026-08-01):** لا تقسيم — هو "Guide" مرجعي متماسك (26 قالباً مدمجاً). يُوثَّق في الخرائط كـ Guide وليس Catalog. | 🟡 **لا يُقسَّم — توثيق فقط** |
+
+**القاعدة:** أي تقسيم فعلي يُنفَّذ عبر SCP منفصل بعد موافقة Majed — لا يُقسَّم هنا تلقائياً.
+**الأولوية:** TERA_RUNTIME_TEMPLATES ✅ مكتمل — التالي: PROTOCOLS، ثم Preparation_Files.