@tera-system/core 0.1.0

package/core/tera-system/consulting-helpers/BTCA_METHODOLOGY_FRAMEWORK.md

@@ -0,0 +1,195 @@
+# BTCA Methodology Framework — إطار المنهجية
+
+> **اقرأني:** قبل بدء أي استشارة BTCA. هذا الملف يوجّه طريقة عملك: كيف تجمع المعلومات، كيف تحللها، كيف تصنف استنتاجاتك.
+>
+> **لا تقرأني:** في بداية Session عادية أو في Track A/B.
+
+---
+
+## 1. تصنيف الأدلة — التفصيل الكامل
+
+### 1.1 المبدأ
+
+كل **نتيجة تحليلية، ادعاء، فجوة، استنتاج أو توصية** في أي تقرير BTCA يجب أن تحمل تصنيف دليل. لا يلزم تصنيف العناوين، الشروحات العامة، الجداول التعريفية أو المحتوى التنظيمي.
+
+### 1.2 المستويات الخمسة
+
+| المستوى | الرمز | متى يُستخدم | ما يليها |
+|---------|:-----:|-------------|----------|
+| **Confirmed Fact** ✅ | `[CF]` | المعلومة مؤكدة من وثيقة رسمية أو مصدرين مستقلين على الأقل | يمكن البناء عليها مباشرة |
+| **Stakeholder Statement** 🗣️ | `[SS]` | المعلومة من مقابلة مع شخص واحد، غير مؤكدة وثائقياً | تحتاج تدقيقاً بمصدر إضافي قبل أن ترتفع إلى CF |
+| **Consultant Inference** 🧠 | `[CI]` | استنتاج تحليلي من قرائن متوفرة — لم يذكره أحد صراحة | يُذكر صراحة أنه استنتاج مع ذكر المقدمات |
+| **Recommendation** 💡 | `[R]` | توصية مقترحة للحل — مبنية على CF و SS و CI | لا تُقدَّم بدون أدلة تدعمها |
+| **Validation Required** ⚠️ | `[VR]` | المعلومة ناقصة أو غير مؤكدة — تحتاج قراراً من Majed أو بيانات إضافية | تمنع أي استنتاج أو توصية مبنية عليها |
+
+### 1.3 أمثلة تطبيقية
+
+| المعلومة | التصنيف | لماذا؟ |
+|----------|:-------:|--------|
+| "الهيكل التنظيمي يضم 5 أقسام حسب الوثيقة الرسمية" | ✅ `[CF]` | مؤكدة بوثيقة |
+| "مدير المشتريات قال إن الموافقات تستغرق أسبوعاً" | 🗣️ `[SS]` | إفادة شخص واحد |
+| "بما أن طلبات الشراء تتكرر أسبوعياً، فالاحتمال الأكبر عدم وجود سياسة مشتريات" | 🧠 `[CI]` | استنتاج تحليلي |
+| "يُنصح بفصل المشتريات عن المستودعات" | 💡 `[R]` | توصية |
+| "عدد الموظفين الفعلي غير معروف" | ⚠️ `[VR]` | يحتاج بيانات إضافية |
+
+### 1.4 قاعدة الترقية
+
+```
+[SS] + مصدر ثانٍ = [CF]
+[CI] + تأكيد من Majed = [CF]
+[VR] + بيانات جديدة = ترقية إلى المستوى المناسب
+[R] بحاجة إلى [CF] أو [SS] كافٍ لدعمها
+```
+
+---
+
+## 2. مراحل العمل — 5 مراحل
+
+### المرحلة 1: فهم الطلب
+
+| البند | الإجراء |
+|-------|---------|
+| الهدف | استلام نطاق الاستشارة من Majed |
+| المدخلات | تكليف Majed + معلومات أولية عن العميل |
+| المخرجات | Scope Note + قائمة أصحاب المصلحة للمقابلات |
+| الأسئلة التوجيهية | ما هو القسم/العملية المستهدفة؟ ما هي حدود الاستشارة؟ من هم الأشخاص المعنيون؟ |
+
+### المرحلة 2: جمع المعلومات
+
+| البند | الإجراء |
+|-------|---------|
+| الهدف | جمع أدلة تشغيلية كافية + بحث خارجي عن معايير الصناعة |
+| المصادر | مقابلات، وثائق، تقارير، بيانات، ملاحظات ميدانية، **domain-research-agent** |
+| المخرجات | ملاحظات مصنّفة + Domain Research Report |
+| قاعدة | على الأقل مصدرين لكل مجال تحليلي رئيسي |
+
+**متى تستخدم البحث الخارجي في هذه المرحلة؟**
+- قبل المقابلات ← ابحث عن الصناعة لصياغة أسئلة أفضل
+- بعد المقابلات ← ابحث عن فجوات إضافية قد لا يكون الزبون واعياً بها
+- عند الحاجة لمعايير ← ابحث عن المعيار المناسب للمجال
+
+**كيف تستخدم `domain-research-agent`؟**
+استخدم أداة `task` مع `subagent_type: "domain-research-agent"` وسؤال بحثي محدد مثل:
+- "ما هي أفضل الممارسات في إدارة المشتريات لشركات المقاولات المتوسطة؟"
+- "ما هو الهيكل التنظيمي النموذجي لقسم المستودعات في المصانع؟"
+- "ما هي المعايير الدولية لزمن دورة الطلب (Order-to-Cash Cycle)؟"
+
+### المرحلة 3: التحليل
+
+| البند | الإجراء |
+|-------|---------|
+| الهدف | تحليل الفجوات، رسم As-Is و To-Be — **مع مقارنة خارجية** |
+| الأدوات | Gap Analysis، Business Process Mapping، Stakeholder Matrix، **Domain Research Report (من المرحلة 2)** |
+| المخرجات | 02_AS_IS + 03_GAP |
+| تصنيف | كل نتيجة تحليلية تُصنّف حسب تصنيف الأدلة |
+
+**كيف تستخدم نتائج البحث في التحليل؟**
+- قارن وضع الزبون الحالي مع معايير الصناعة (من Domain Research Report)
+- حدد الفجوات بناءً على المقارنة وليس فقط بناءً على رأي الزبون
+- ضع المصدر: "حسب دراسة [اسم المصدر] (2025)، متوسط زمن دورة المشتريات هو X — وضع الزبون Y"
+
+**تنبيه:** نتائج البحث الخارجي = مرجع للمقارنة وليس حقيقة مطلقة. كل صناعة وكل سوق له خصوصيته. لا تفرض معياراً لا ينطبق على سياق الزبون.
+
+### المرحلة 4: التوصيات
+
+| البند | الإجراء |
+|-------|---------|
+| الهدف | تصميم الحلول المقترحة |
+| المخرجات | 04_TO_BE → 08_KPI |
+| قاعدة | كل توصية مدعومة بـ CF أو SS |
+| حد | لا تزيد التوصيات عن 10 توصيات رئيسية لكل مشروع |
+
+### المرحلة 5: التقرير النهائي
+
+| البند | الإجراء |
+|-------|---------|
+| الهدف | تجميع كل المخرجات في حزمة متكاملة |
+| المخرجات | 09_ROADMAP + 10_RISKS + FINAL_REPORT |
+| مراجعة | يُعرض على Majed أولاً، ثم يُسلّم للزبون بعد الاعتماد |
+
+---
+
+## 3. دليل المقابلات
+
+### 3.1 قبل المقابلة
+
+1. حدد الهدف من المقابلة: ماذا تريد أن تعرف؟
+2. اقرأ أي وثائق متوفرة عن الشركة أولاً
+3. حضّر 5-7 أسئلة مفتوحة كحد أقصى
+
+### 3.2 أثناء المقابلة
+
+1. استمع أكثر مما تسأل — نسبة الاستماع 70%، الكلام 30%
+2. اسأل عن **الواقع** لا عن **الرأي**: "كم مرة تتكرر هذه العملية؟" لا "هل تعتقد أنها جيدة؟"
+3. اسأل عن **الأدلة**: "هل يوجد دليل مكتوب لهذه السياسة؟"
+4. اسأل عن **المشكلات الملموسة**: "أعطني مثالاً على آخر مرة تأخرت فيها موافقة"
+5. لا تعد بأي حلول أثناء المقابلة — دورك جمع معلومات، ليس تقديم حلول فورية
+
+### 3.3 بعد المقابلة
+
+1. دوّن الملاحظات في نفس اليوم
+2. صنّف كل معلومة حسب تصنيف الأدلة
+3. حدد أي فجوات معلوماتية تحتاج مقابلة إضافية
+
+---
+
+## 4. مصفوفة أصحاب المصلحة
+
+| الفئة | التعريف | منهجية التعامل |
+|-------|---------|---------------|
+| **صانع القرار** | من يقرر مصير الاستشارة (غالباً المدير العام) | مقابلة أولى وأخيرة — تركيز على التوجهات |
+| **المشرف المباشر** | مدير القسم المستهدف | مقابلة تفصيلية — تركيز على العمليات |
+| **المنفّذ** | موظف يقوم بالعمل الفعلي | مقابلة عملية — تركيز على التحديات اليومية |
+| **المتأثر** | قسم آخر يتأثر بالتغيير | مقابلة قصيرة — تركيز على نقاط التكامل |
+
+---
+
+## 5. هيكل التقرير النهائي (FINAL_BUSINESS_TRANSFORMATION_REPORT.md)
+
+```
+# FINAL_BUSINESS_TRANSFORMATION_REPORT — [اسم العميل]
+**تاريخ:** [التاريخ]
+**إعداد:** BTCA — مستشار التحول المؤسسي
+**النطاق:** [وصف نطاق الاستشارة]
+
+---
+
+## الملخص التنفيذي (Executive Summary)
+[صفحة واحدة — المشكلة، التحليل، التوصيات الرئيسية، الأثر المتوقع]
+
+---
+
+## 1. خلفية المشروع
+[من هو العميل، لماذا الاستشارة، النطاق]
+
+## 2. منهجية العمل
+[كيف جمعت المعلومات، مصادر الأدلة، تصنيفها]
+
+## 3. تحليل الوضع الحالي (As-Is)
+[الهيكل الحالي، العمليات الحالية، نقاط القوة والضعف]
+[جميع النتائج مصنّفة حسب تصنيف الأدلة]
+
+## 4. تحليل الفجوات (Gap Analysis)
+[الفجوات بين الوضع الحالي والمستهدف، مصنّفة حسب الخطورة]
+
+## 5. النموذج التشغيلي المستهدف (To-Be)
+[الهيكل المقترح، العمليات المستقبلية، الأدوار]
+
+## 6. التوصيات
+[قائمة التوصيات الرئيسية — كل توصية مدعومة بأدلة]
+
+## 7. خطة التنفيذ (Roadmap)
+[مراحل التنفيذ، الجدول الزمني، الأولويات]
+
+## 8. المخاطر وإدارة التغيير
+[المخاطر المتوقعة، خطة التخفيف، إدارة مقاومة التغيير]
+
+## 9. الخاتمة
+[خلاصة + دعوة للعمل]
+
+---
+
+> **تصنيفات الأدلة المستخدمة في هذا التقرير:**
+> ✅ `[CF]` = Confirmed Fact | 🗣️ `[SS]` = Stakeholder Statement
+> 🧠 `[CI]` = Consultant Inference | 💡 `[R]` = Recommendation | ⚠️ `[VR]` = Validation Required
+```

package/core/tera-system/consulting-helpers/BTCA_REPORT_TEMPLATES.md

@@ -0,0 +1,266 @@
+# BTCA Report Templates — قوالب التقارير
+
+> **اقرأني:** عند بدء مشروع BTCA جديد — اختر القوالب المناسبة حسب نطاق الاستشارة.
+>
+> **لا تقرأني:** في بداية Session عادية.
+
+---
+
+## دليل اختيار القوالب
+
+| حجم المشروع | القوالب المطلوبة | القوالب الاختيارية |
+|:-----------:|:-----------------:|:------------------:|
+| **صغير** (قسم واحد، عملية واحدة) | 01, 03, 04, 09, FINAL | 02, 07, 08 |
+| **متوسط** (قسم كامل، عدة عمليات) | 01, 02, 03, 04, 07, 09, FINAL | 05, 06, 08, 10 |
+| **كبير** (شركة كاملة، هيكلة شاملة) | 01–10, FINAL | — |
+
+---
+
+## قالب 01: EXECUTIVE_ASSESSMENT.md
+
+```
+# التقييم التنفيذي — [اسم العميل]
+**التاريخ:** [التاريخ]
+**النطاق:** [القسم/العمليات المستهدفة]
+
+## المخرجات المتوقعة
+- [النتيجة المتوقعة 1] [CF/SS/CI]
+- [النتيجة المتوقعة 2] [CF/SS/CI]
+
+## المنهجية المقترحة
+[مقابلات، مراجعة وثائق، تحليل بيانات]
+
+## الجدول الزمني المقترح
+| المرحلة | المدة | المخرجات |
+|---------|:-----:|----------|
+| جمع المعلومات | [عدد] أيام | — |
+| التحليل | [عدد] أيام | 02_AS_IS + 03_GAP |
+| التوصيات | [عدد] أيام | 04_TO_BE → 08_KPI |
+| التقرير النهائي | [عدد] أيام | FINAL_REPORT |
+
+## أصحاب المصلحة المعنيون
+- [الاسم/المنصب]
+- [الاسم/المنصب]
+```
+
+---
+
+## قالب 02: AS_IS_OPERATING_MODEL.md
+
+```
+# تحليل الوضع الحالي — [اسم العميل/القسم]
+
+## 1. الهيكل التنظيمي الحالي
+[وصف الهيكل الحالي + عدد الموظفين]
+
+## 2. العمليات الحالية
+### العملية: [اسم العملية]
+| الخطوة | المسؤول | المدة | الوصف |
+|:------:|:-------:|:-----:|-------|
+| 1 | [دور] | [وقت] | [وصف] [CF/SS] |
+| 2 | [دور] | [وقت] | [وصف] [CF/SS] |
+
+## 3. نقاط القوة
+- [نقطة قوة 1] [CF]
+- [نقطة قوة 2] [CF]
+
+## 4. نقاط الضعف
+- [نقطة ضعف 1] [SS/CF]
+- [نقطة ضعف 2] [CI]
+```
+
+---
+
+## قالب 03: GAP_ANALYSIS.md
+
+```
+# تحليل الفجوات — [اسم العميل/القسم]
+
+| # | المجال | الوضع الحالي [CF/SS/CI] | الوضع المستهدف | الفجوة | الخطورة |
+|:-:|:------:|:-----------------------:|:--------------:|:------:|:-------:|
+| 1 | [مجال] | [وصف] | [وصف] | [فجوة] | High/Med |
+| 2 | [مجال] | [وصف] | [وصف] | [فجوة] | Med/Low |
+
+## الفجوات الحرجة (High)
+- [فجوة 1] — [تأثيرها]
+- [فجوة 2] — [تأثيرها]
+```
+
+---
+
+## قالب 04: TARGET_OPERATING_MODEL.md
+
+```
+# النموذج التشغيلي المستهدف — [اسم العميل/القسم]
+
+## 1. الهيكل التنظيمي المقترح
+[وصف الهيكل الجديد]
+
+## 2. العمليات المستهدفة
+### العملية: [اسم العملية] — To-Be
+| الخطوة | المسؤول | المدة المستهدفة | الوصف |
+|:------:|:-------:|:---------------:|-------|
+| 1 | [دور] | [وقت] | [وصف] |
+| 2 | [دور] | [وقت] | [وصف] |
+
+## 3. مبررات التغيير
+- [مبرر 1] — يستند إلى [CF/SS من الملف 02/03]
+```
+
+---
+
+## قالب 05: ORGANIZATION_STRUCTURE.md
+
+```
+# الهيكل التنظيمي المقترح — [اسم العميل]
+
+## الهيكل الحالي (ملخص)
+[رسم/وصف مختصر للهيكل الحالي]
+
+## الهيكل المقترح
+```
+[المدير العام]
+  ├── [إدارة/قسم 1]
+  │   ├── [وحدة 1.1]
+  │   └── [وحدة 1.2]
+  ├── [إدارة/قسم 2]
+  │   ├── [وحدة 2.1]
+  │   └── [وحدة 2.2]
+```
+
+## مبررات التعديلات
+| التعديل | المبرر | الدليل |
+|:-------:|--------|:------:|
+| [تعديل] | [سبب] | [CF/SS] |
+```
+
+---
+
+## قالب 06: PROCESS_REDESIGN.md
+
+```
+# إعادة تصميم العمليات — [اسم العميل]
+
+## العملية: [اسم العملية]
+
+### الوضع الحالي (As-Is)
+[وصف + رسم العملية الحالية]
+
+### المشكلات المكتشفة
+- [مشكلة 1] [CF/SS]
+- [مشكلة 2] [CI]
+
+### الوضع المستهدف (To-Be)
+[وصف + رسم العملية الجديدة]
+
+### الفروقات
+| البعد | الحالي | المستهدف | الأثر |
+|:-----:|:------:|:--------:|:-----:|
+| المدة | [وقت] | [وقت] | [توفير] |
+| الخطوات | [عدد] | [عدد] | [تبسيط] |
+| المسؤول | [دور] | [دور] | [وضوح] |
+```
+
+---
+
+## قالب 07: ROLES_AND_RESPONSIBILITIES.md
+
+```
+# الأدوار والمسؤوليات — [اسم العميل]
+
+## مصفوفة RACI — [العملية/القسم]
+| المهمة | المسؤول (R) | المعني (A) | يُستشار (C) | يُطلَع (I) |
+|:------:|:-----------:|:----------:|:-----------:|:----------:|
+| [مهمة 1] | [دور] | [دور] | [دور] | [دور] |
+| [مهمة 2] | [دور] | [دور] | [دور] | [دور] |
+
+## توصيات الوظائف
+| الوظيفة المقترحة | المبرر | المهارات المطلوبة |
+|:----------------:|--------|:-----------------:|
+| [وظيفة] | [سبب] | [مهارات] |
+```
+
+---
+
+## قالب 08: KPI_FRAMEWORK.md
+
+```
+# مؤشرات الأداء المقترحة — [اسم العميل]
+
+| # | المؤشر | الوحدة | المستهدف | تكرار القياس | المصدر |
+|:-:|:------:|:------:|:--------:|:------------:|:------:|
+| 1 | [KPI] | [%] | [رقم] | شهري | [نظام/تقرير] |
+| 2 | [KPI] | [يوم] | [رقم] | أسبوعي | [نظام/تقرير] |
+```
+
+---
+
+## قالب 09: IMPLEMENTATION_ROADMAP.md
+
+```
+# خطة تنفيذ التوصيات — [اسم العميل]
+
+## الأولويات
+| الأولوية | التوصية | الأثر | الجهد | الجدول |
+|:--------:|:-------:|:-----:|:-----:|:------:|
+| P1 | [توصية] | عالي | منخفض | الأسبوع 1-2 |
+| P2 | [توصية] | عالي | متوسط | الشهر 1 |
+| P3 | [توصية] | متوسط | عالي | الشهر 2-3 |
+
+## المراحل
+### المرحلة 1: [اسم] (الأسبوع 1-2)
+- [إجراء 1]
+- [إجراء 2]
+
+### المرحلة 2: [اسم] (الشهر 1)
+- [إجراء 1]
+```
+
+---
+
+## قالب 10: RISKS_AND_CHANGE_PLAN.md
+
+```
+# المخاطر وإدارة التغيير — [اسم العميل]
+
+## المخاطر
+| الخطر | الاحتمال | التأثير | التخفيف |
+|:-----:|:--------:|:-------:|---------|
+| [خطر] | High/Med | High/Med | [إجراء] |
+
+## خطة إدارة التغيير
+| النشاط | الجمهور | التوقيت |
+|:------:|:-------:|:-------:|
+| [نشاط] | [فئة] | [وقت] |
+```
+
+---
+
+## القالب النهائي: FINAL_BUSINESS_TRANSFORMATION_REPORT.md
+
+يُجمّع من الملفات 01–10 حسب المشروع. الهيكل الإلزامي:
+
+```
+# FINAL_BUSINESS_TRANSFORMATION_REPORT — [اسم العميل]
+**تاريخ:** [التاريخ]
+**إعداد:** BTCA — مستشار التحول المؤسسي
+
+## الملخص التنفيذي
+[وجة واحدة — المشكلة، التحليل، التوصيات الرئيسية]
+
+## الملفات المرفقة
+| # | الملف | الصفحات | الحالة |
+|:-:|:-----:|:-------:|:------:|
+| 1 | 01_EXECUTIVE_ASSESSMENT.md | — | Draft |
+| 2 | 02_AS_IS_OPERATING_MODEL.md | — | Draft |
+| ... | ... | ... | ... |
+
+## التوصيات الرئيسية
+1. [توصية] [R] — مبينة على [CF/SS]
+2. [توصية] [R] — مبينة على [CF/CI]
+
+## الخطوات التالية
+- مراجعة Majed
+- اعتماد التقرير
+- تسليم للزبون
+```

package/core/tera-system/design-system/ACCESSIBILITY_RULES.md

@@ -0,0 +1,31 @@
+# Accessibility Rules
+
+## Purpose
+
+Set baseline accessibility requirements for UI tasks.
+
+## Required Baseline
+
+- Text contrast must be readable on all backgrounds.
+- Focus states must be visible for keyboard navigation.
+- Buttons and links must have clear labels.
+- Form fields must have labels and error states.
+- Color must not be the only indicator of status.
+- Click/tap targets should be practical on mobile.
+- Loading, empty, success, and error states must be planned for important workflows.
+
+## UI Acceptance Checks
+
+For each UI task:
+
+```text
+Contrast checked: Yes / No / N/A
+Focus states present: Yes / No / N/A
+Responsive behavior defined: Yes / No / N/A
+RTL/LTR respected: Yes / No / N/A
+Error/empty/loading states defined: Yes / No / N/A
+```
+
+## Rule
+
+If accessibility behavior is missing from the design source, record a Design Gap instead of guessing.

package/core/tera-system/design-system/COMPONENT_LIBRARY_SCHEMA.md

@@ -0,0 +1,46 @@
+# Component Library Schema
+
+## Purpose
+
+Define how component style rules should be recorded before implementation.
+
+## Required Component Rule Format
+
+```text
+Component:
+Purpose:
+Variants:
+States:
+Spacing:
+Typography:
+Color tokens:
+Interaction:
+Accessibility:
+Forbidden:
+```
+
+## Core Components
+
+- Button
+- Input
+- Select
+- Textarea
+- Checkbox / Radio
+- Card
+- Table
+- Sidebar
+- Topbar
+- Tabs
+- Modal / Drawer
+- Alert / Toast
+- Badge / Tag
+- Pagination
+- Empty State
+- Loading State
+
+## Rules
+
+- Do not create a new component style when an approved pattern exists.
+- Reuse existing implemented components before adding variants.
+- Any new variant must map to a task acceptance criterion.
+- UI tasks must list the components affected.

package/core/tera-system/design-system/DESIGN_MD_INTEGRATION.md

@@ -0,0 +1,59 @@
+# DESIGN.md Integration Protocol
+
+## Purpose
+
+Use `getdesign.md` / DESIGN.md as an approved external design-system source, without making it mandatory or allowing direct brand copying.
+
+## Status
+
+```text
+getdesign.md = Approved External Design System Source
+getdesign.md != mandatory design source
+getdesign.md != final executable project design
+```
+
+## Workflow
+
+1. Identify the application type and visual need.
+2. Search/select up to 3 suitable DESIGN.md options.
+3. Present style qualities to the user, not brand imitation promises.
+4. After selection, save raw source in:
+
+```text
+project-preparation/design-source/DESIGN.md
+project-preparation/design-source/DESIGN_SOURCE_NOTES.md
+```
+
+5. Convert raw DESIGN.md into:
+
+```text
+project-preparation/28_UI_UX_GUIDELINES.md
+```
+
+6. Apply client branding overrides.
+7. Record forbidden styling and brand-imitation risks.
+8. EngineeringAgent implements only from `28_UI_UX_GUIDELINES.md`.
+
+## Required DESIGN_SOURCE_NOTES.md
+
+```text
+Selected source:
+Reason:
+Useful patterns:
+Excluded patterns:
+Client color/font overrides:
+Brand imitation risk:
+License/legal notes if known:
+Final decision by Tera:
+```
+
+## Prohibited Use
+
+- Do not copy a famous brand identity literally.
+- Do not promise the client a design “like Stripe/Linear/Apple” as a deliverable identity.
+- Do not let EngineeringAgent execute directly from raw DESIGN.md without `28_UI_UX_GUIDELINES.md`.
+- Do not use a DESIGN.md that conflicts with client scope, accessibility, RTL/LTR needs, or approved Technology Profile.
+
+## getdesign.app
+
+`getdesign.app` / URL extraction may be used only as optional External URL Analysis when available and approved. It is not a mandatory dependency.