@tera-system/core 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (161) hide show
  1. package/LICENSE.md +13 -0
  2. package/MANIFEST.json +24 -0
  3. package/README.md +67 -0
  4. package/RELEASES.md +28 -0
  5. package/WELCOME.md +35 -0
  6. package/agents/application-blueprint.md +407 -0
  7. package/agents/auditor.md +665 -0
  8. package/agents/design-reviewer.md +392 -0
  9. package/agents/domain-expert-agent.md +510 -0
  10. package/agents/domain-research-agent.md +360 -0
  11. package/agents/engineering-agent-dotnet.md +218 -0
  12. package/agents/engineering-agent-phaser.md +275 -0
  13. package/agents/engineering-agent-typescript.md +300 -0
  14. package/agents/engineering-agent.md +143 -0
  15. package/agents/monitor.md +395 -0
  16. package/agents/production-erp-expert.md +506 -0
  17. package/agents/project-knowledge-agent.md +271 -0
  18. package/agents/qa-agent.md +498 -0
  19. package/agents/tera-business-transformation-consultant.md +290 -0
  20. package/agents/tera-client-engagement.md +891 -0
  21. package/agents/tera-software-designer.md +237 -0
  22. package/agents/tera-strategic-advisor.md +325 -0
  23. package/agents/tera-system-evolution.md +759 -0
  24. package/agents/tera.md +520 -0
  25. package/agents/ui-designer.md +426 -0
  26. package/commands/tera-approve.md +34 -0
  27. package/commands/tera-diagnose.md +47 -0
  28. package/commands/tera-gate.md +40 -0
  29. package/commands/tera-help.md +41 -0
  30. package/commands/tera-new-project.md +35 -0
  31. package/commands/tera-plan.md +34 -0
  32. package/commands/tera-request-build.md +45 -0
  33. package/commands/tera-resume.md +34 -0
  34. package/commands/tera-review.md +52 -0
  35. package/commands/tera-status.md +38 -0
  36. package/commands/tera-update.md +48 -0
  37. package/core/project-control/templates/TASK_TEMPLATE.md +146 -0
  38. package/core/tera-system/AGENT_ACTIVATION_MATRIX.md +285 -0
  39. package/core/tera-system/AGENT_DEPENDENCY_MAP.md +117 -0
  40. package/core/tera-system/AGENT_GENERATION_TEMPLATE.md +312 -0
  41. package/core/tera-system/AGENT_PERMISSION_MODEL.md +343 -0
  42. package/core/tera-system/AIS_PROTOCOL.md +191 -0
  43. package/core/tera-system/TERA_AGENT_CONDUCT.md +102 -0
  44. package/core/tera-system/TERA_CONTINUOUS_IMPROVEMENT_POLICY.md +111 -0
  45. package/core/tera-system/TERA_DISTRIBUTION_POLICY.md +291 -0
  46. package/core/tera-system/TERA_PROJECT_DECISION.md +281 -0
  47. package/core/tera-system/TERA_USER_GUIDE.md +462 -0
  48. package/core/tera-system/TOOLING_AND_MCP_POLICY.md +285 -0
  49. package/core/tera-system/TeraApplicationQuestionBank.md +362 -0
  50. package/core/tera-system/TeraArchitectureMap.md +91 -0
  51. package/core/tera-system/TeraClientPolicy.md +366 -0
  52. package/core/tera-system/TeraHelperAgents.md +970 -0
  53. package/core/tera-system/TeraPolicyMap.md +131 -0
  54. package/core/tera-system/TeraPreExecutionGate.md +818 -0
  55. package/core/tera-system/TeraPreparationDocumentationGovernance.md +370 -0
  56. package/core/tera-system/TeraPricingPolicy.md +674 -0
  57. package/core/tera-system/TeraProjectIntakePolicy.md +164 -0
  58. package/core/tera-system/TeraScenarioStressTests.md +168 -0
  59. package/core/tera-system/TeraSubAgents.md +854 -0
  60. package/core/tera-system/TeraSystemMaintenanceChecklist.md +80 -0
  61. package/core/tera-system/TeraTokenPolicy.md +362 -0
  62. package/core/tera-system/Tera_Project_Preparation_Files.md +1045 -0
  63. package/core/tera-system/agent-helpers/application-blueprint-details.md +177 -0
  64. package/core/tera-system/client-helpers/tera-client-engagement-discovery-domains.md +99 -0
  65. package/core/tera-system/client-helpers/tera-client-engagement-gates.md +258 -0
  66. package/core/tera-system/client-helpers/tera-client-engagement-pricing.md +341 -0
  67. package/core/tera-system/client-helpers/tera-client-engagement-protocols.md +692 -0
  68. package/core/tera-system/consulting-helpers/BTCA_METHODOLOGY_FRAMEWORK.md +195 -0
  69. package/core/tera-system/consulting-helpers/BTCA_REPORT_TEMPLATES.md +266 -0
  70. package/core/tera-system/design-system/ACCESSIBILITY_RULES.md +31 -0
  71. package/core/tera-system/design-system/COMPONENT_LIBRARY_SCHEMA.md +46 -0
  72. package/core/tera-system/design-system/DESIGN_MD_INTEGRATION.md +59 -0
  73. package/core/tera-system/design-system/DESIGN_REVIEW_STANDARDS.md +241 -0
  74. package/core/tera-system/design-system/DESIGN_SOURCE_PROTOCOL.md +61 -0
  75. package/core/tera-system/design-system/DESIGN_SYSTEM_OVERVIEW.md +66 -0
  76. package/core/tera-system/design-system/DESIGN_TOKENS_SCHEMA.md +66 -0
  77. package/core/tera-system/design-system/EXTERNAL_REFERENCE_ANALYSIS.md +52 -0
  78. package/core/tera-system/design-system/FIGMA_INTEGRATION.md +138 -0
  79. package/core/tera-system/design-system/INTERNAL_KITS_INDEX.md +26 -0
  80. package/core/tera-system/design-system/LAYOUT_PATTERNS.md +52 -0
  81. package/core/tera-system/design-system/MOBILE_UI_UX_STANDARDS.md +342 -0
  82. package/core/tera-system/design-system/RTL_LTR_RULES.md +39 -0
  83. package/core/tera-system/design-system/UI_ACCEPTANCE_GATE.md +80 -0
  84. package/core/tera-system/design-system/kits/KIT_ADMIN_DASHBOARD.md +102 -0
  85. package/core/tera-system/engineering-governance/ENGINEERING_AGENT_RESPONSIBILITIES.md +210 -0
  86. package/core/tera-system/engineering-governance/ENGINEERING_BEST_PRACTICES.md +468 -0
  87. package/core/tera-system/engineering-governance/ENGINEERING_GOVERNANCE_GATE.md +131 -0
  88. package/core/tera-system/engineering-governance/ENGINEERING_REVIEW_CHECKLIST.md +129 -0
  89. package/core/tera-system/engineering-governance/QUALITY_GATE_THRESHOLDS.md +159 -0
  90. package/core/tera-system/engineering-helpers/engineering-agent-core.md +171 -0
  91. package/core/tera-system/knowledge-base/OPENHANDS_ARCHITECTURE_REFERENCE.md +243 -0
  92. package/core/tera-system/knowledge-base/manufacturing/00_INDEX.md +32 -0
  93. package/core/tera-system/knowledge-base/manufacturing/01_MANUFACTURING_ERP_CORE_CONCEPTS.md +7 -0
  94. package/core/tera-system/knowledge-base/manufacturing/02_SAP_MANUFACTURING_RESEARCH.md +7 -0
  95. package/core/tera-system/knowledge-base/manufacturing/03_DYNAMICS_365_MANUFACTURING_RESEARCH.md +7 -0
  96. package/core/tera-system/knowledge-base/manufacturing/04_ORACLE_MANUFACTURING_RESEARCH.md +7 -0
  97. package/core/tera-system/knowledge-base/manufacturing/05_ODOO_MANUFACTURING_RESEARCH.md +7 -0
  98. package/core/tera-system/knowledge-base/manufacturing/06_ERPNEXT_MANUFACTURING_RESEARCH.md +7 -0
  99. package/core/tera-system/knowledge-base/manufacturing/07_MANUFACTURING_COSTING_GUIDE.md +7 -0
  100. package/core/tera-system/knowledge-base/manufacturing/08_PRODUCTION_DISCOVERY_QUESTIONS.md +7 -0
  101. package/core/tera-system/knowledge-base/manufacturing/09_MANUFACTURING_BLUEPRINT_CHECKLIST.md +7 -0
  102. package/core/tera-system/knowledge-base/manufacturing/10_PRODUCTION_TEST_SCENARIOS.md +7 -0
  103. package/core/tera-system/knowledge-base/manufacturing/11_QUALITY_REWORK_AND_SCRAP_GUIDE.md +7 -0
  104. package/core/tera-system/knowledge-base/manufacturing/12_MRP_AND_PLANNING_GUIDE.md +7 -0
  105. package/core/tera-system/knowledge-base/manufacturing/13_LOCAL_AND_REGIONAL_MANUFACTURING_CONTEXT.md +7 -0
  106. package/core/tera-system/knowledge-base/manufacturing/14_VENDOR_COMPARISON_MATRIX.md +7 -0
  107. package/core/tera-system/product-standards/maintenance-apps/BEST_PRACTICES_DOMAIN.md +325 -0
  108. package/core/tera-system/product-standards/maintenance-apps/STANDARD_DEFINITION.md +142 -0
  109. package/core/tera-system/profiles/PROFILES_INDEX.md +57 -0
  110. package/core/tera-system/profiles/TEMPLATE.md +47 -0
  111. package/core/tera-system/profiles/dotnet-blazor-ef.md +76 -0
  112. package/core/tera-system/profiles/dotnet-razorpages-adonet.md +137 -0
  113. package/core/tera-system/profiles/dotnet-wpf-sqlite.md +159 -0
  114. package/core/tera-system/profiles/effect-bun-opencode.md +109 -0
  115. package/core/tera-system/profiles/flutter-mobile.md +369 -0
  116. package/core/tera-system/profiles/nextjs-prisma.md +110 -0
  117. package/core/tera-system/profiles/phaser-react-node.md +302 -0
  118. package/core/tera-system/profiles/react-pwa.md +97 -0
  119. package/core/tera-system/runtime/CLIENT_DISCOVERY_PROTOCOL.md +145 -0
  120. package/core/tera-system/runtime/DOMAIN_INTELLIGENCE_PROTOCOL.md +124 -0
  121. package/core/tera-system/runtime/MVP_DEFINITION_PROTOCOL.md +176 -0
  122. package/core/tera-system/runtime/TERA_RUNTIME_CHECKLISTS.md +646 -0
  123. package/core/tera-system/runtime/TERA_RUNTIME_PROTOCOLS.md +50 -0
  124. package/core/tera-system/runtime/TERA_RUNTIME_PROTOCOLS_CLIENT.md +355 -0
  125. package/core/tera-system/runtime/TERA_RUNTIME_PROTOCOLS_CORE.md +799 -0
  126. package/core/tera-system/runtime/TERA_RUNTIME_TEMPLATES.md +908 -0
  127. package/core/tera-system/runtime/TERA_RUNTIME_TEMPLATES_DELIVERY.md +584 -0
  128. package/core/tera-system/runtime/TERA_RUNTIME_TEMPLATES_PREPARATION.md +376 -0
  129. package/core/tera-system/runtime/TERA_SOLUTION_PREPARATION_PROTOCOL.md +335 -0
  130. package/core/tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md +397 -0
  131. package/core/tera-system/runtime/VERSION_LIFECYCLE_PROTOCOL.md +296 -0
  132. package/core/tera-system/semgrep-rules/README.md +32 -0
  133. package/core/tera-system/semgrep-rules/tera-security.yml +66 -0
  134. package/core/tera-system/semgrep-rules/tera-standards.yml +49 -0
  135. package/core/tera-system/teranoo-ui/README.md +48 -0
  136. package/core/tera-system/teranoo-ui/components/button.tsx +51 -0
  137. package/core/tera-system/teranoo-ui/components/card.tsx +49 -0
  138. package/core/tera-system/teranoo-ui/components/dashboard-layout.tsx +36 -0
  139. package/core/tera-system/teranoo-ui/components/data-table.tsx +146 -0
  140. package/core/tera-system/teranoo-ui/components/empty-state.tsx +31 -0
  141. package/core/tera-system/teranoo-ui/components/kpi-card.tsx +42 -0
  142. package/core/tera-system/teranoo-ui/components/page-header.tsx +25 -0
  143. package/core/tera-system/teranoo-ui/components/search-input.tsx +40 -0
  144. package/core/tera-system/teranoo-ui/components/sidebar.tsx +66 -0
  145. package/core/tera-system/teranoo-ui/components/stats-card.tsx +37 -0
  146. package/core/tera-system/teranoo-ui/registry.json +77 -0
  147. package/core/tera-system/teranoo-ui/styles/teranoo-theme.css +61 -0
  148. package/opencode.tera.example.json +30 -0
  149. package/package.json +37 -0
  150. package/scripts/build.mjs +110 -0
  151. package/scripts/install.js +244 -0
  152. package/scripts/lib/license.mjs +90 -0
  153. package/scripts/lib/public-key.pem +3 -0
  154. package/scripts/tera-license.mjs +63 -0
  155. package/tools/tera-clean.ps1 +97 -0
  156. package/tools/tera-fetch.ps1 +165 -0
  157. package/tools/tera-release.ps1 +96 -0
  158. package/tools/tera-schedule.ps1 +59 -0
  159. package/tools/tera-update.ps1 +472 -0
  160. package/tools/tera-watch.ps1 +154 -0
  161. package/tools/update-client-repositories.ps1 +92 -0
@@ -0,0 +1,111 @@
1
+ <!-- © 2026 Majed Khaireddin (Alabasi1980). Tera System — Proprietary. All rights reserved. -->
2
+
3
+ # TERA CONTINUOUS IMPROVEMENT POLICY
4
+
5
+ ## 1. الغرض
6
+
7
+ هذه السياسة توجّه جميع العملاء الأساسيين في منظومة Tera إلى التزام **اليقظة النظامية** — أي ملاحظة الفجوات، الخلل، التضخم، أو فرص التحسين في المنظومة والإبلاغ عنها، بدلاً من تجاهلها أو اعتبارها خارج نطاق المسؤولية.
8
+
9
+ ---
10
+
11
+ ## 2. السياق
12
+
13
+ هذه المؤسسة والمنظومة ما زالت في مرحلة تأسيس وتشغيل أولي، وهذا المشروع يُعد من أوائل المشاريع التجريبية/التشغيلية لدينا.
14
+
15
+ لذلك، يُتوقع من كل عميل أثناء عمله أن يبقى متنبهاً لقابلية تحسين المنظومة نفسها، وليس فقط تنفيذ المهمة الموكلة إليه.
16
+
17
+ ---
18
+
19
+ ## 3. مجالات المراقبة — ما يجب أن ينتبه له العميل
20
+
21
+ أثناء العمل على أي مرحلة أو مهمة، إذا لاحظ العميل أي مما يلي، يجب عليه عدم تجاهله:
22
+
23
+ | المجال | أمثلة |
24
+ |--------|-------|
25
+ | نقص في الملف التعريفي أو التعليمات التشغيلية | دور العميل غير محدّد بدقة، تعليمات ناقصة |
26
+ | خلل أو غموض في المنظومة أو آلية العمل | سياسة متناقضة، بروتوكول غير مكتمل |
27
+ | أوامر أو قيود غير مناسبة لطبيعة الدور | العميل ممنوع من فعل شيء ضروري لأداء عمله |
28
+ | خطوات أو أعمال غير ضرورية تسبب بطئاً أو تعطيلاً | تكرار في المهام، مراحل لا قيمة مضافة لها |
29
+ | صلاحيات أو أدوات إضافية يحتاجها العميل | MCP، صلاحية قراءة/كتابة، أداة مفقودة |
30
+ | مهام غير مناسبة للدور أو يجب نقلها لعميل آخر | تداخل مسؤوليات بين العملاء |
31
+ | تحسينات مقترحة على طريقة العمل أو الملفات أو البروتوكولات | إعادة هيكلة، دمج ملفات، تبسيط إجراءات |
32
+ | أي ملاحظة من شأنها تحسين جودة المؤسسة أو كفاءة العملاء أو تقليل الأخطاء والتضخم | — |
33
+
34
+ ---
35
+
36
+ ## 4. آلية الإبلاغ — ما يجبفعله العميل عند اكتشاف ملاحظة مهمة
37
+
38
+ عند اكتشاف أي ملاحظة تستوفي معايير البند §3، على العميل القيام بالخطوات التالية:
39
+
40
+ 1. **إبلاغ Majed** بها بوضوح في ردّه.
41
+ 2. **توضيح أثرها** على العمل، إن وجد.
42
+ 3. **اقتراح حل عملي** مختصر إن أمكن.
43
+ 4. **تسجيلها** داخل ملف التطبيق التالي:
44
+ ```
45
+ project-control/AGENT_GAPS_LOG.md
46
+ ```
47
+
48
+ ### 4.1 صيغة التسجيل في AGENT_GAPS_LOG.md
49
+
50
+ يجب أن تكون الملاحظة منظّمة بالشكل التالي:
51
+
52
+ ```md
53
+ ## GAP-[رقم تلقائي أو مؤقت] — [عنوان مختصر]
54
+
55
+ - Date:
56
+ - Agent:
57
+ - Context:
58
+ - Observation:
59
+ - Impact:
60
+ - Recommended Action:
61
+ - Severity: Low / Medium / High
62
+ - Status: Open
63
+ ```
64
+
65
+ ### 4.2 تنبيه مهم — لا تسجيل للتفاصيل الصغيرة
66
+
67
+ لا يُستخدم هذا المسار لتسجيل ملاحظات عادية أو تفاصيل تنفيذية صغيرة.
68
+ يُستخدم فقط للملاحظات التي تكشف:
69
+
70
+ - خللاً
71
+ - نقصاً
72
+ - تضارباً
73
+ - فرصة تحسين حقيقية
74
+ - حاجة تطوير في المنظومة أو في دور العميل نفسه
75
+
76
+ ---
77
+
78
+ ## 5. استمرارية العمل
79
+
80
+ على العميل أن **يستمر في تنفيذ مهمته الأساسية**، ولا يوقف العمل بسبب الملاحظة إلا إذا كان الخلل مؤثراً على:
81
+
82
+ - سلامة القرار
83
+ - جودة التنفيذ
84
+
85
+ في هذه الحالة، على العميل إيقاف العمل مؤقتاً، إبلاغ Majed، وانتظار التوجيه.
86
+
87
+ ---
88
+
89
+ ## 6. العلاقة مع بقية المنظومة
90
+
91
+ | الملف/الآلية | العلاقة بهذه السياسة |
92
+ |--------------|----------------------|
93
+ | `project-control/AGENT_GAPS_LOG.md` | الوجهة الرسمية لتسجيل الملاحظات |
94
+ | `TeraSystemEvolutionAgent` | المسؤول عن مراجعة ومعالجة الإدخالات في AGENT_GAPS_LOG.md |
95
+ | `TeraPreExecutionGate.md` §2.5 | التذكير التشغيلي بقراءة هذه السياسة قبل التنفيذ |
96
+ | `TeraPolicyMap.md` | يوثق هذه السياسة كمصدر حقيقة رسمي |
97
+ | `tera-system/AIS_PROTOCOL.md` | بروتوكول AIS — آلية تسجيل وتحسين استباقية (مكملة لـ GAPS) |
98
+ | `project-control/AGENT_IMPROVEMENT_SUGGESTIONS.md` | السجل المركزي لاقتراحات AIS |
99
+ | `TeraSystemEvolutionAgent` | المسؤول أيضاً عن معالجة اقتراحات AIS (مراجعة، تصنيف، تحويل لـ SCP) |
100
+
101
+ ---
102
+
103
+ ## 7. أحكام ختامية
104
+
105
+ - هذه السياسة تخضع لنفس قواعد التطوير: أي تعديل عليها يحتاج `SYSTEM_CHANGE_PROPOSAL` وموافقة Majed.
106
+ - لا يجوز لأي عميل تعديل هذه السياسة أو استخدامها كمبرر لتعديل صلاحياته دون المرور بـ `TeraSystemEvolutionAgent`.
107
+ - هذه السياسة دائمة — وليست إعلاناً مؤقتاً.
108
+
109
+ ---
110
+
111
+ > *"المنظومة تتحسن فقط عندما يلاحظ من يعمل فيها ما يحتاج تحسيناً."*
@@ -0,0 +1,291 @@
1
+ <!-- © 2026 Majed Khaireddin (Alabasi1980). Tera System — Proprietary. All rights reserved. -->
2
+
3
+ # TERA Distribution Policy — سياسة توزيع Tera على مستودعات العملاء
4
+
5
+ ## 1. الغرض
6
+
7
+ تُعرّف هذه السياسة **الطريقة الرسمية** لتوزيع منظومة Tera (الملفات المُدارة تابعاً لـ Tera) على مستودعات العملاء، وترقية هذه المستودعات، وضمان:
8
+ - تثبيت إصدار معروف (Version Pinning) — لا نسخ متفرقة ولا تتبع تلقائي للفروع
9
+ - تحقق من سلامة الملفات (SHA256) قبل كل تثبيت
10
+ - فصل ملكية واضح بين ملفات Tera وملفات العميل
11
+ - مسار ترقية واسترجاع آمنين بأمر واحد
12
+
13
+ > **مصدر الحقيقة:** هذه السياسة هي المرجع الوحيد لآلية التوزيع. الخرائط (Policy Map / Architecture Map) تشير إليها فقط.
14
+ > **المصدر:** SCP-2026-08-15-009 — موافق عليه 2026-08-15 (تحديث SCP-007/SCP-008).
15
+
16
+ ---
17
+
18
+ ## 2. نموذج التوزيع
19
+
20
+ ```text
21
+ TeraSystem الرئيسي (المستودع الأصلي — RepositoryUrl)
22
+ │ إصدار رسمي عبر Tag (tera-vX.Y.Z)
23
+
24
+ tera-fetch.ps1 ← جلب من المستودع الأصلي (HTTPS/SSH موثق) + بناء حزمة متحققة
25
+
26
+ Release Package (ملفات Tera-managed + SHA256SUMS + TERA_RELEASE_MANIFEST.json)
27
+
28
+
29
+ تثبيت/ترقية آلي عبر tera-update.ps1 (-SourcePath أو -RepositoryUrl)
30
+
31
+ مستودع عميل (Client repository)
32
+ ├── .opencode/ ← Tera-managed
33
+ ├── tera-system/ ← Tera-managed
34
+ ├── tera-workshop/ ← Tera-managed (اختياري للتوزيع)
35
+ ├── .tera/lock.json ← Tera-managed (ملف القفل)
36
+ ├── .tera/backups/ ← نسخ استرجاع محلية غير موزعة
37
+ ├── project-control/ ← Client-owned
38
+ ├── project-preparation/ ← Client-owned
39
+ ├── project-inputs/ ← Client-owned
40
+ └── clients/ + كود التطبيق ← Client-owned
41
+ ```
42
+
43
+ ### 2.0 الاستمداد من المستودع الأصلي (نموذج الأصالة — الخيار ب)
44
+
45
+ - **مرساة الثقة:** المستودع الأصلي الخاص (HTTPS/SSH موثق) هو المصدر الوحيد المعتمد للإصدارات.
46
+ - **القناة:** HTTPS موثوق أو SSH — مصادقة على مستوى git؛ لا تتبع تلقائي لأي فرع.
47
+ - **التثبيت:** الـ Lockfile يحفظ **Commit SHA كامل** للـ Tag — التحقق النهائي هو SHA، لا اسم الفرع.
48
+ - **tera-fetch.ps1** يجلب الـ Tag من `RepositoryUrl` ويبني حزمة متحققة (Manifest + SHA256SUMS) قبل أي تثبيت.
49
+ - **رفض الانتحال:** استبدال حزمة كاملة (ملفات + SUMS) لا يكفي — الـ Commit SHA في الـ Lockfile يجب أن يطابق Manifest المُجرى من الأصل.
50
+ - لا توقيع GPG إلزامي حالياً (القرار ب)؛ يُعاد النظر عند فتح التوزيع العام خارج المستودع الخاص.
51
+
52
+ ### 2.1 قواعد الإصدار
53
+
54
+ | القاعدة | الوصف |
55
+ |---|---|
56
+ | الترويس | كل إصدار رسمي = `git tag tera-vX.Y.Z` (مثلاً `tera-v2.5.0`) |
57
+ | مرجع الإصدار | الـ Lockfile يحفظ **Commit SHA كامل** + Tag + Version — SHA هو الحقيقة، وليس الفرع |
58
+ | القنوات | `stable` (افتراضي) / `beta` (اختياري) — تُسجَّل في الـ Lockfile |
59
+ | التثبيت | كل عميل يُثبَّت على Tag محدد بوعي؛ عميل يبقى على `tera-v2.0.0` وآخر ينتقل لـ `tera-v2.5.0` |
60
+ | المنع المطلق | **لا تتبع تلقائي لـ `main` أو `develop` في أي مستودع عميل** |
61
+
62
+ ### 2.2 Lockfile — `.tera/lock.json`
63
+
64
+ في جذر كل مستودع عميل:
65
+
66
+ ```json
67
+ {
68
+ "version": "2.5.0",
69
+ "tag": "tera-v2.5.0",
70
+ "commit": "FULL_COMMIT_SHA",
71
+ "channel": "stable",
72
+ "files": [
73
+ ".opencode/agents/example.md",
74
+ "tera-system/example.md",
75
+ "tera-workshop/example.ps1"
76
+ ]
77
+ }
78
+ ```
79
+
80
+ - **version:** رقم الإصدار (بدون بادئة tera-)
81
+ - **tag:** الـ Tag الرسمي
82
+ - **commit:** SHA الكامل للمرجع — هو مؤشر الحقيقة
83
+ - **channel:** stable أو beta
84
+ - **files:** قائمة الملفات المُدارة في الإصدار؛ تُستخدم لاكتشاف الملفات المحذوفة في الترقية
85
+
86
+ عند غياب `lock.json` أو تلفه → **يتوقف التحديث**؛ التثبيت الأول وحده يُسمح به مع `-Initialize` صريح. لا يُفترض أي إصدار افتراضي.
87
+
88
+ ---
89
+
90
+ ## 3. عقد الملكية (Ownership Contract)
91
+
92
+ | المسار داخل مستودع العميل | الملكية | التعامل |
93
+ |---|---|---|
94
+ | `.opencode/` | **Tera** | يستبدله المُحدِّث عند الترقية |
95
+ | `tera-system/` | **Tera** | يستبدله المُحدِّث عند الترقية |
96
+ | `tera-workshop/` (اختياري في التوزيع) | **Tera** | يُوزَّع فقط إذا كانت الحزمة تشمله |
97
+ | `.tera/lock.json` | **Tera** | يكتبه المُحدِّث تلقائياً |
98
+ | `.tera/backups/` | **Tera updater** | نسخ استرجاع محلية؛ لا تُضمَّن في الحزمة ولا في commit |
99
+ | `project-control/` | العميل | لا يلمسه المُحدِّث أبداً |
100
+ | `project-preparation/` | العميل | لا يلمسه المُحدِّث أبداً |
101
+ | `project-inputs/` | العميل | لا يلمسه المُحدِّث أبداً |
102
+ | `clients/`, كود التطبيق | العميل | لا يلمسه المُحدِّث أبداً |
103
+
104
+ ### 3.1 قواعد صارمة
105
+
106
+ 1. **المُحدِّث يرفض** أي استبدال لملف Tera-managed عُدّله العميل محلياً → يُبلَّغ بالتعارض ولا يُستبدل.
107
+ 2. **ممنوع** تعديل ملفات Tera-managed يدوياً داخل مستودع العميل. أي تحسين عام يبدأ من مستودع Tera الرئيسي ثم يُصدَّر كنسخة جديدة.
108
+ 3. حذف أي مجلد Tera-managed من مستودع العميل (مثل حذف `tera-system/`) يُعد تعديلاً محلياً → يمنع التحديث حتى يُعاد.
109
+
110
+ ---
111
+
112
+ ## 4. أدوات التوزيع
113
+
114
+ | الأداة | المسار | الوظيفة |
115
+ |---|---|---|
116
+ | `tera-fetch.ps1` | `tera-workshop/tools/` | جلب الإصدارات من المستودع الأصلي (List) + بناء حزمة متحققة (Fetch) |
117
+ | `tera-update.ps1` | `tera-workshop/tools/` | تحديث مستودع عميل **واحد** — وضعا Plan و Apply |
118
+ | `update-client-repositories.ps1` | `tera-workshop/tools/` | تحديث **دفعات** من المستودعات — وضعا Plan و Apply |
119
+ | `tera-release.ps1` | `tera-workshop/tools/` | بناء حزمة إصدار متحقق منها من Tag + Manifest + SHA256SUMS |
120
+
121
+ ### 4.1 tera-fetch.ps1 — الجلب من المستودع الأصلي
122
+
123
+ ```powershell
124
+ # عرض الإصدارات المتاحة في المستودع الأصلي
125
+ pwsh .\tera-workshop\tools\tera-fetch.ps1 -RepositoryUrl "https://github.com/Alabasi1980/TeraSystem" -List
126
+
127
+ # فحص: هل يوجد إصدار أحدث من المثبت حالياً؟ (قراءة فقط — لا يعدّل شيئاً)
128
+ pwsh .\tera-workshop\tools\tera-fetch.ps1 -RepositoryUrl "https://github.com/Alabasi1980/TeraSystem" -Check -RepoPath "D:\My Projects\TeraWebsite"
129
+
130
+ # بناء حزمة إصدار موثقة من المستودع الأصلي
131
+ pwsh .\tera-workshop\tools\tera-fetch.ps1 -RepositoryUrl "https://github.com/Alabasi1980/TeraSystem" -Version tera-v2.5.0 -Channel stable -OutPath "C:\TeraReleases\tera-v2.5.0"
132
+ ```
133
+
134
+ **وضع Check:** يقارن الإصدار المثبت في `lock.json` بأحدث إصدار في الأصل، ويخبرك بما يلي:
135
+ - أنت على أحدث إصدار ✅
136
+ - يوجد إصدار أحدث + أمر الترقية الجاهز
137
+ - لا تثبيت مسبق + أمر التثبيت الأول
138
+
139
+ لا يُنشئ Check أي تعديل — قراءة فقط.
140
+
141
+ ### 4.1b الإشعار التلقائي — tera-watch.ps1 + tera-schedule.ps1
142
+
143
+ تسجيل الإشعار التلقائي مرة واحدة لكل مستودع عميل:
144
+
145
+ ```powershell
146
+ # تسجيل مهمة Windows Task Scheduler (عند تسجيل الدخول + كل 6 ساعات)
147
+ pwsh .\tera-workshop\tools\tera-schedule.ps1 `
148
+ -RepositoryUrl "https://github.com/Alabasi1980/TeraSystem.git" `
149
+ -RepoPath "D:\My Projects\TeraWebsite"
150
+
151
+ # إزالة المهمة
152
+ pwsh .\tera-workshop\tools\tera-schedule.ps1 -Unregister
153
+ ```
154
+
155
+ السلوك:
156
+ - عند وجود إصدار أحدث → **Windows Toast** أصلي يظهر على سطح المكتب + ملف `.tera/update-status.json` يُحدَّث.
157
+ - ملف الحالة قابل للقراءة من أي جلسة (بما فيها OpenCode) لمعرفة `updateAvailable`.
158
+ - تشغيل يدوي لمرة واحدة: `pwsh .\tera-workshop\tools\tera-watch.ps1 -RepositoryUrl "..." -RepoPath "..." -Once`
159
+ - رموز الخروج: 0 = محدّث، 2 = يوجد تحديث، 1 = خطأ.
160
+
161
+ ### 4.2 tera-update.ps1 — أوامر
162
+
163
+ ```powershell
164
+ # فحص جاف من حزمة محلية
165
+ pwsh .\tera-workshop\tools\tera-update.ps1 -Version tera-v2.5.0 -Channel stable -Mode Plan -SourcePath "C:\TeraReleases\tera-v2.5.0"
166
+
167
+ # فحص جاف مباشرة من المستودع الأصلي (استمداد حي)
168
+ pwsh .\tera-workshop\tools\tera-update.ps1 -Version tera-v2.5.0 -Channel stable -Mode Plan -RepositoryUrl "https://github.com/Alabasi1980/TeraSystem"
169
+
170
+ # التنفيذ الفعلي من المستودع الأصلي
171
+ pwsh .\tera-workshop\tools\tera-update.ps1 -Version tera-v2.5.0 -Channel stable -Mode Apply -RepositoryUrl "https://github.com/Alabasi1980/TeraSystem"
172
+ ```
173
+
174
+ ### 4.3 tera-release.ps1 — بناء الإصدار
175
+
176
+ ```powershell
177
+ pwsh .\tera-workshop\tools\tera-release.ps1 -Version 2.5.0 -Tag tera-v2.5.0 -Channel stable -OutputPath "C:\TeraReleases\tera-v2.5.0"
178
+ ```
179
+
180
+ ينشئ الأمر حزمة مجلدية متحققة تحتوي على `TERA_RELEASE_MANIFEST.json` و`SHA256SUMS` من محتوى الـ Tag نفسه (لا من working tree). يرفض تعارض Version/Tag.
181
+
182
+ مسارات إضافية:
183
+ ```powershell
184
+ pwsh .\tera-workshop\tools\tera-update.ps1 -Version tera-v2.5.0 -Channel stable -Mode Apply -RepoPath "C:\clients\CLIENT-X\APP-Y" -SourcePath "C:\TeraReleases\tera-v2.5.0"
185
+
186
+ # التثبيت الأول يحتاج تصريحاً صريحاً
187
+ pwsh .\tera-workshop\tools\tera-update.ps1 -Version tera-v2.5.0 -Channel stable -Mode Apply -Initialize -SourcePath "C:\TeraReleases\tera-v2.5.0"
188
+ ```
189
+
190
+ ### 4.4 سلوك المُحدِّث (سلسلة تحقق إلزامية)
191
+
192
+ ```text
193
+ 1. قراءة Manifest وSHA256SUMS — غيابهما أو نقصهما = إيقاف
194
+ 2. مطابقة version/tag/commit/channel والتحقق من كل hash قبل أي نسخ
195
+ 3. فحص lock.json؛ التالف/الناقص = إيقاف، والتثبيت الأول يحتاج -Initialize
196
+ 4. فرض Git وفحص التعديلات المحلية على ملفات Tera-managed
197
+ 5. منع المسارات المطلقة و.. وأي ملف خارج Tera-managed roots
198
+ 6. منع الكتابة عبر أي Reparse Point (symlink/junction) في مسار الوجهة
199
+ 7. مع -Initialize: رفض أي ملف/مجلد غير متتبع يتعارض مع ملفات الحزمة
200
+ 8. الفرق بين الحزمة والحالي → (جديد/مستبدل/كما هو/محذوف)
201
+ 9. [Plan] تقرير فقط — لا كتابة
202
+ 10. [Apply] backup → نسخ/حذف مضبوط → تحديث lock.json → staged diff check → commit
203
+ 11. عند الفشل: استرجاع من backup وتقرير واضح
204
+ ```
205
+
206
+ ### 4.5 update-client-repositories.ps1 — الدفعات
207
+
208
+ ```powershell
209
+ pwsh .\tera-workshop\tools\update-client-repositories.ps1 -Version tera-v2.5.0 -Channel stable -Mode Plan -SourcePath "C:\TeraReleases\tera-v2.5.0" -ReposFile "C:\Tera\client-repositories.txt"
210
+ pwsh .\tera-workshop\tools\update-client-repositories.ps1 -Version tera-v2.5.0 -Channel stable -Mode Apply -SourcePath "C:\TeraReleases\tera-v2.5.0" -ReposFile "C:\Tera\client-repositories.txt"
211
+
212
+ # دفعات مباشرة من المستودع الأصلي
213
+ pwsh .\tera-workshop\tools\update-client-repositories.ps1 -Version tera-v2.5.0 -Channel stable -Mode Apply -RepositoryUrl "https://github.com/Alabasi1980/TeraSystem" -ReposFile "C:\Tera\client-repositories.txt"
214
+ ```
215
+
216
+ - يقبل ملف قائمة مستودعات (سطر لكل مسار) أو JSON بالشكل `{ "repositories": ["..."] }`
217
+ - يستخدم SourcePath أو RepositoryUrl واحداً متحققاً لكل المستودعات
218
+ - كل مستودع يستقبل Plan أولاً؛ فشل أي Plan يمنع كل Apply
219
+ - Apply الدفعي ليس ذرّياً بين المستودعات؛ يُسجّل نجاح/فشل كل مستودع منفرداً
220
+
221
+ ---
222
+
223
+ ## 5. قائمة الإصدار الرسمي (Release Checklist)
224
+
225
+ تُنفَّذ في مستودع Tera الرئيسي قبل نشر أي إصدار:
226
+
227
+ ```text
228
+ 1. التحقق أن SHA256SUMS ومحتوى الحزمة مطابقان للمرجع
229
+ 2. إنشاء Tag: git tag tera-vX.Y.Z (بدون رسالة عشوائية) ثم دفعه للمستودع الأصلي
230
+ 3. بناء الحزمة: tera-release.ps1 من الـ Tag (ملفات Tera-managed فقط)
231
+ 4. التحقق اليدوي: تثبيت تجريبي على مستودع وهمي (Plan ثم Apply)
232
+ 5. النشر ثم التسجيل في SYSTEM_EVOLUTION_LOG.md
233
+ ```
234
+
235
+ **حماية الإصدار:** لا يُنشر Tag إلا بعد نجاح خطوة 5 (تثبيت تجريبي) — منع إصدار "مكسور" ينتشر للعملاء.
236
+
237
+ ---
238
+
239
+ ## 6. الترقية والاسترجاع
240
+
241
+ ### الترقية
242
+ ```powershell
243
+ # من حزمة محلية
244
+ pwsh .\tera-workshop\tools\tera-update.ps1 -Version tera-v2.5.0 -Channel stable -Mode Plan -SourcePath "C:\TeraReleases\tera-v2.5.0"
245
+ pwsh .\tera-workshop\tools\tera-update.ps1 -Version tera-v2.5.0 -Channel stable -Mode Apply -SourcePath "C:\TeraReleases\tera-v2.5.0"
246
+
247
+ # مباشرة من المستودع الأصلي
248
+ pwsh .\tera-workshop\tools\tera-update.ps1 -Version tera-v2.5.0 -Channel stable -Mode Plan -RepositoryUrl "https://github.com/Alabasi1980/TeraSystem"
249
+ pwsh .\tera-workshop\tools\tera-update.ps1 -Version tera-v2.5.0 -Channel stable -Mode Apply -RepositoryUrl "https://github.com/Alabasi1980/TeraSystem"
250
+ ```
251
+
252
+ ### الاسترجاع (Rollback)
253
+ ```powershell
254
+ # العودة إلى إصدار سابق مثبت:
255
+ pwsh .\tera-workshop\tools\tera-update.ps1 -Version tera-v2.0.0 -Channel stable -Mode Plan -SourcePath "C:\TeraReleases\tera-v2.0.0"
256
+ pwsh .\tera-workshop\tools\tera-update.ps1 -Version tera-v2.0.0 -Channel stable -Mode Apply -SourcePath "C:\TeraReleases\tera-v2.0.0"
257
+ ```
258
+ - الاسترجاع = تحديث إلى SHA سابق — نفس الآلية، بلا "مسار خاص"
259
+ - ملفات العميل لا تتأثر إطلاقاً
260
+
261
+ ---
262
+
263
+ ## 7. العلاقة مع بقية المنظومة
264
+
265
+ | الملف | العلاقة |
266
+ |---|---|
267
+ | `tera-system/TeraPolicyMap.md` | يوثّق هذه السياسة كمصدر حقيقة لموضوع التوزيع |
268
+ | `tera-system/TeraArchitectureMap.md` | يوضّح طبقة التوزيع ودور `tera-workshop/tools/` |
269
+ | `project-control/SYSTEM_EVOLUTION_LOG.md` | يسجّل كل إصدار/ترقية منفذة |
270
+ | `tera-system/TOOLING_AND_MCP_POLICY.md` | السياسة الحاكمة للأدوات — المُحدِّث أداة رسمية ضمن `tera-workshop/tools/` |
271
+ | `.gitattributes` | `cr-at-eol` — أساس سلامة `git diff --check` عند التحديث |
272
+
273
+ ---
274
+
275
+ ## 8. الحوكمة
276
+
277
+ - تعديل هذه السياسة يحتاج `SYSTEM_CHANGE_PROPOSAL` وموافقة Majed.
278
+ - تجاوز أي بوابة (SHA، التعارض المحلي، قائمة الإصدار) **ممنوع** حتى بأمر تنفيذي.
279
+ - هذه السياسة دائمة — وليست إعلاناً مؤقتاً.
280
+
281
+ ---
282
+
283
+ ## 9. سجل الإصدارات (Release History)
284
+
285
+ | الإصدار | التاريخ | القناة | أبرز المحتوى |
286
+ |---|---|---|---|
287
+ | `tera-v1.0.0` | 2026-08-15 | stable | أول إصدار رسمي موثق: آلية توزيع كاملة (release/fetch/update/batch)، تنظيف شامل، وإصلاحات Pilot (gitattributes، commit detection) |
288
+
289
+ ---
290
+
291
+ > *"التوزيع بلا ترويس فوضى. الترويس بلا تحقق انتحال. التحقق بلا استرجاع رهان."*