@tera-system/pro 0.1.4 → 0.2.1

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

@@ -1,335 +0,0 @@
-# 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` — تعريف مُهندس