@tera-system/core 0.1.0

package/core/tera-system/runtime/TERA_SOLUTION_PREPARATION_PROTOCOL.md

@@ -0,0 +1,335 @@
+# Tera Solution Preparation Protocols
+
+هذه البروتوكولات هي مادة دعم تشغيلية رسمية لـ **ApplicationBlueprintAgent (مُهندس)** — Solution Preparation Authority للمراحل 1–4.
+استخدمها عندما يطلب ملف التعريف المضغوط سلوكاً تشغيلياً مفصلاً.
+
+**Reference:** SCP-2026-07-28-118 — Phase ownership refactor
+**Split from:** `tera-system/runtime/TERA_RUNTIME_PROTOCOLS.md` (2026-07-28)
+**Primary consumer:** مُهندس (ApplicationBlueprintAgent)
+**Secondary consumer:** TCEA (cross-reference only)
+
+---
+
+## 1. Solution Preparation Lifecycle
+
+### 1.1 Phase 1 — Project Intake & Discovery
+
+عند بدء مشروع جديد (داخلي) أو استلام handoff (خارجي):
+
+1. **للمشاريع الخارجية:** تحقق من اكتمال حزمة TCEA (`TERA_HANDOFF_PACKAGE.md`). لا تُعد discovery العميل أو التسعير.
+2. **للمشاريع الداخلية:** ادخل وضع الاكتشاف — استمع، لخّص، اسأل.
+3. كشف الفجوات التقنية/الوظيفية اللازمة للتحضير.
+4. تطبيع المدخلات داخل application workspace.
+5. إنتاج `00_PROJECT_INPUTS.md`.
+6. معلومات ناقصة → سؤال موثق إلى Majed. لا تخمّن.
+
+**قواعد صارمة:**
+- لا معلومات مهمة تبقى في chat فقط.
+- لا تحضير قبل تأكيد الفهم.
+- لا تخطيط تنفيذي أو TASK-COD-* قبل اعتماد `PROJECT_MASTER_PLAN.md`.
+- الأسئلة توجّه عبر Majed فقط؛ لا تواصل مباشر مع العميل أو TCEA.
+
+**مرجع الأسئلة:** `tera-system/TeraApplicationQuestionBank.md`
+**بروتوكول الاكتشاف الكامل:** `tera-system/runtime/CLIENT_DISCOVERY_PROTOCOL.md`
+
+### 1.2 Phase 2 — Project Decision Formation
+
+1. تقييم العمق: Risk, Uncertainty, Complexity.
+2. تصنيف المشروع: نوعه، حجمه، تعقيده.
+3. تحديد ملفات التحضير المطلوبة: Required / Conditional / Deferred / Not Required.
+4. اقتراح Technology Profile.
+5. إنتاج `TERA_PROJECT_DECISION.md`.
+6. عرض القرار على Majed.
+
+**القالب:** `tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md` §1
+
+### 1.3 Phase 3 — Preparation Planning
+
+1. قراءة `Tera_Project_Preparation_Files.md` ككتالوج.
+2. تصنيف كل ملف مطلوب مع تحديد المالك والترتيب والتبعيات.
+3. إنتاج `PREPARATION_PLAN.md`.
+4. موافقة Majed.
+
+**قاعدة:** لا إنشاء ملفات ولا توليد عملاء في هذه المرحلة.
+
+**القالب:** `tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md` §2
+
+### 1.4 Phase 4 — Preparation Delegation & Baseline
+
+1. إنتاج `AGENT_DELEGATION_PLAN.md`.
+2. تفويض `TASK-PREP-*` لعملاء التحضير بنطاقات كتابة واضحة.
+3. تطبيق Maker/Checker وCross-Review على كل ملف.
+4. تتبع كل متطلب إلى مصدره ومساره وشاشته وبياناته ومعيار قبوله.
+5. إدارة lifecycle ملفات التحضير حتى `Module Baseline Approved` فأعلى.
+
+**القالب:** `tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md` §3
+
+---
+
+## 2. Depth Assessment Protocol
+
+قبل بدء أي مشروع، قيّم 3 أبعاد:
+
+| البعد | المستويات |
+|--------|----------|
+| Risk | Low / Medium / High |
+| Uncertainty | Low / Medium / High |
+| Domain Complexity | Low / Medium / High |
+
+**التقييم السريع:** إذا كانت جميع الأبعاد Low → Core Only مباشرة.
+**مصفوفة Depth Control:** `tera-system/agent-helpers/application-blueprint-details.md §1`
+
+---
+
+## 3. Research and Domain Intelligence Protocol
+
+### 3.1 متى تبحث
+
+- فجوة معرفية محددة تمنع إكمال التحضير.
+- المجال غير مألوف.
+- معلومات handoff غير كافية لتوصية دقيقة.
+- تقييم ثقة منخفض (Low) في Self-Verification.
+
+### 3.2 قواعد البحث
+
+1. سؤال محدد ودقيق — لا بحث مفتوح.
+2. `webfetch` للأسئلة البسيطة أولاً.
+3. DomainResearchAgent للأسئلة المعقدة.
+4. DomainExpertAgent لتحليل النتائج.
+5. ProductionERPExpert لموديولات التصنيع/الإنتاج.
+
+### 3.3 No-Guessing Rule
+
+```text
+إذا كانت معلومة أساسية مفقودة:
+→ توقف
+→ وثق في BLUEPRINT_OPEN_QUESTIONS.md
+→ اسأل Majed
+→ لا تخمّن
+```
+
+### 3.4 Source Tags
+
+| الوسم | المعنى | متى يدخل baseline |
+|-------|--------|-------------------|
+| `[Confirmed by Majed]` | مؤكد من Majed | فوراً |
+| `[Research Hint]` | من بحث خارجي | بعد تأكيد Majed |
+| `[Assumption]` | افتراض | بعد تأكيد Majed |
+| `[Unresolved]` | غير معروف | بعد قرار Majed |
+
+---
+
+## 4. Cross-Review and Document Lifecycle
+
+### 4.1 Maker / Checker Model
+
+- **Maker:** عميل تحضير متخصص يكتب الملف.
+- **Checker:** عميل تحضير مختلف يراجع الاتساق.
+- **Orchestrator:** مُهندس يخطط ويدير lifecycle.
+
+### 4.2 Document States
+
+```text
+Draft → Under Cross-Review → Module Baseline Approved → System Pending Integration → System Approved → Locked
+```
+
+### 4.3 Cross-Review Rules
+
+1. كل ملف تحضيري يمر بـ Cross-Review قبل `Module Baseline Approved`.
+2. الـ Checker يجب أن يكون مختلفاً عن الـ Maker.
+3. الـ Checker يراجع: اتساق مع upstream، اكتمال، حالات الحافة، التبعيات.
+4. Issues → يعاد الملف إلى Draft مع توثيق findings.
+5. موافقة Checker → مُهندس يرفع الحالة.
+
+**المرجع الكامل:** `tera-system/TeraPreparationDocumentationGovernance.md`
+
+---
+
+## 5. Solution Readiness Gate
+
+### 5.1 الحالات
+
+```text
+PASS
+REVISION_REQUIRED
+BLOCKED
+```
+
+### 5.2 معايير PASS
+
+```text
+[ ] Approved commercial source or internal owner direction documented
+[ ] Scope, exclusions, deferred items, and assumptions explicit
+[ ] Every material requirement has traceable source
+[ ] Users, roles, workflows, screens, data, integrations mutually consistent
+[ ] Normal, empty, error, exception, and material edge cases covered
+[ ] Security, performance, deployment, compliance, migration triggers evaluated
+[ ] UI work has approved Design Source Decision and executable guidance
+[ ] Acceptance criteria observable and testable
+[ ] Required preparation documents reached required lifecycle states
+[ ] Cross-document reconciliation passed
+[ ] No unresolved High/Critical item
+[ ] No Low Confidence section
+[ ] No Pending Approval item required for Phase 5
+[ ] Active Technology Profile confirmed or blocking decision recorded
+[ ] Recommended implementation sequencing exists (guidance, not plan)
+```
+
+---
+
+## 6. Clarification Protocol
+
+أثناء Phase 5–7، إذا احتاج Tera توضيحاً:
+
+```text
+Tera → سؤال موثق إلى Majed
+Majed → مُهندس
+مُهندس → جواب موثق أو مراجعة baseline
+Majed → Tera
+```
+
+إذا كان السؤال يمس النطاق التجاري: Majed → TCEA/client → مُهندس → تحديث baseline.
+
+**تصنيف الأسئلة أثناء التنفيذ:**
+
+| النوع | صاحب القرار/المسار |
+|---|---|
+| Technical implementation detail | Tera يقرر ويسجل ADR |
+| Preparation inconsistency | يعاد إلى مُهندس عبر Majed |
+| Client behavior/scope ambiguity | Majed → TCEA/client → مُهندس |
+| New scope | Client Change Control |
+| Safety/security blocker | Tera يوقف ويبلغ Majed |
+
+---
+
+## 7. Preparation Agent Delegation Authority
+
+مُهندس يملك صلاحية تنسيق العملاء في **Preparation Mode فقط**:
+
+| الفئة | العملاء | الصلاحية |
+|-------|---------|----------|
+| بحث وتحليل | DomainResearchAgent, DomainExpertAgent, ProductionERPExpert | مسموح — مخرجات `[Research Hint]` |
+| تحضير | RequirementsScopeAgent, BusinessWorkflowAgent, DataDesignAgent, UIUXStructureAgent, SolutionArchitectureAgent, helper agents | مسموح عبر `TASK-PREP-*` |
+| تخطيط اختبارات | qa-agent Planning Mode | مسموح — لا Execution Mode |
+| تصميم بصري | ui-designer Preparation Design Mode | مسموح — وثائق فقط، ممنوع كود |
+| Coding Agents | engineering-agent, engineering-agent-dotnet | ❌ ممنوع |
+| تصميم مهام | tera-software-designer | ❌ يبقى تحت Tera |
+| تدقيق | Auditor | ❌ يبقى تحت Tera/Monitor |
+
+### قواعد التفويض
+
+1. كل `TASK-PREP-*` يجب أن يكون محدوداً بمخرج واحد واضح.
+2. Allowed Write Targets مسارات كاملة (absolute paths).
+3. تفويض → handback → مراجعة → قبول/رفض → المهمة التالية.
+4. لا تفويض بدون `PREPARATION_PLAN.md` معتمد.
+5. أي إنشاء/تفعيل لعميل تحضيري يخضع لموافقة Majed.
+
+---
+
+## 7.5 Content Confirmation Gate — بوابة تأكيد المحتوى (SCP-2026-08-15-016)
+
+> بوابة **مشروطة** — تُفعَّل فقط عندما يكون Content Type = `User-Facing Content` أو `Mixed` (من Discovery — Domain 4).
+
+### التفعيل
+
+```text
+إذا Content Type = User-Facing Content / Mixed (موقع، صفحة هبوط، تسويق، محتوى)
+  → هذه البوابة إلزامية قبل اعتماد التصميم البصري النهائي (28) وقبل Phase 5.
+إذا Application Data فقط (تطبيق قياسي)
+  → البوابة لا تُفعَّل (Anti-Bloat) — يكفي قسم خفيف داخل 07 إن لزم.
+```
+
+### التوقيت
+
+```text
+بعد: إنتاج 07_SCREENS_AND_UI_STRUCTURE.md (الهيكل الوظيفي للشاشات)
+قبل: اعتماد التصميم البصري النهائي (28_UI_UX_GUIDELINES.md) وبدء Phase 5
+```
+
+### المالك والتنفيذ
+
+- **المالك:** مُهندس (ApplicationBlueprintAgent).
+- **الجلسة:** جلسة نقاش واحدة مركزة مع المالك/الزبون — للعملاء الخارجيين تمر عبر Majed (لا تواصل مباشر).
+- **المدخلات:** خريطة الشاشات (07) + قرارات Discovery (التموضع/النبرة/Claims/الخطوط الحمراء).
+
+### لكل شاشة/صفحة (S1..Sn + المشتركة C1/C2) — العناصر التسعة
+
+```text
+1. Purpose            — الغرض من الشاشة
+2. Audience           — الجمهور المستهدف لهذه الشاشة
+3. Primary Message    — الرسالة الأساسية التي يجب أن يفهمها الزائر
+4. Required Content   — المحتوى المطلوب ظهوره (معلومات/بيانات/عناصر)
+5. CTA                — الدعوة للإجراء (إن وُجدت) ووجهتها
+6. Forbidden          — المحتوى الممنوع/الحساس (من الخطوط الحمراء D-015)
+7. Claims المسموحة    — ما يمكن ادعاؤه (أرقام موثقة في مصادر الحقيقة فقط)
+8. Content Priorities — الأولويات بين الرسائل داخل الشاشة
+9. Content Owner      — المالك/المصدر المعتمد للمحتوى
+```
+
+### المخرج
+
+```text
+مشاريع المحتوى:  CONTENT_REQUIREMENTS.md (قالب §41 — لكل شاشة الجدول أعلاه)
+تطبيقات قياسية:  قسم خفيف داخل 07_SCREENS_AND_UI_STRUCTURE.md إن لزم
+```
+
+### القواعد
+
+1. كل قرار محتوى معتمد → إدخال في `CLIENT_DECISION_LOG.md` (تاريخ + D-number + حالة).
+2. **الاعتراض على محتوى يُعالج في الشاشة المعنية فقط** — لا يفتح إعادة تصميم التطبيق.
+3. لا يُخترع محتوى بدل المالك: إذا لم يُجب المالك، يُسجل كـ Open Question — لا افتراض.
+4. نتائج البوابة تُستدعى في Solution Readiness Gate (§9 في application-blueprint.md).
+
+---
+
+## 8. Engineering Handoff Package Protocol
+
+### 8.1 المحتوى الأدنى
+
+1. Workspace and project identity.
+2. Approved scope/version references.
+3. Preparation baseline manifest and lifecycle states.
+4. Requirements traceability summary.
+5. Architecture/technology decisions and constraints.
+6. Design source and UI readiness.
+7. Test and acceptance readiness.
+8. Risks, assumptions, deferred items, non-blocking questions.
+9. Recommended implementation sequence.
+10. Solution Readiness Gate evidence and result.
+11. Majed approval reference.
+
+### 8.2 الموقع
+
+```text
+project-control/ENGINEERING_HANDOFF_PACKAGE.md
+```
+
+### 8.3 القواعد
+
+- لا يستبدل preparation documents؛ هو manifest وتسليم مختصر.
+- يُنتج مرة واحدة لكل مشروع عند Solution Readiness.
+- لا يُعدّل بواسطة TeraAgent.
+- يُستهلك بواسطة TeraAgent عبر Engineering Intake Gate.
+
+---
+
+## 9. Anti-Bloat Rules for Preparation
+
+1. ملفات التحضير: المطلوبة فقط حسب تصنيف المشروع، لا كل الكتالوج.
+2. Draft Seeds: ≤ 3 بدون موافقة Majed.
+3. لا ملفات دعم غير لازمة.
+4. لا قرارات نهائية متنكرة كـ recommendations.
+5. كل ملف له مالك كتابة واحد.
+6. لا ازدواج للمحتوى بين ملفات التحضير.
+
+---
+
+## 10. References
+
+- `tera-system/Tera_Project_Preparation_Files.md` — كتالوج ملفات التحضير
+- `tera-system/TeraPreparationDocumentationGovernance.md` — حوكمة lifecycle
+- `tera-system/TeraProjectIntakePolicy.md` — سياسة intake
+- `tera-system/TeraClientPolicy.md` — سياسة العميل
+- `tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md` — قوالب التحضير
+- `tera-system/agent-helpers/application-blueprint-details.md` — تفاصيل Depth Control و C4
+- `.opencode/agents/application-blueprint.md` — تعريف مُهندس