@tera-system/core 0.5.0 → 0.6.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 (41) hide show
  1. package/MANIFEST.json +7 -7
  2. package/RELEASES.md +13 -0
  3. package/agents/application-blueprint.md +6 -6
  4. package/agents/auditor.md +19 -2
  5. package/agents/tera-client-engagement.md +6 -6
  6. package/agents/tera-system-evolution.md +1 -1
  7. package/agents/tera.md +2 -0
  8. package/commands/tera-approve.md +43 -34
  9. package/commands/tera-diagnose.md +2 -0
  10. package/commands/tera-gate.md +2 -0
  11. package/commands/tera-help.md +1 -0
  12. package/commands/tera-new-project.md +32 -35
  13. package/commands/tera-plan.md +2 -0
  14. package/commands/tera-reconcile.md +35 -0
  15. package/commands/tera-request-build.md +2 -0
  16. package/commands/tera-resume.md +2 -0
  17. package/commands/tera-review.md +2 -0
  18. package/commands/tera-status.md +2 -0
  19. package/core/tera-system/AGENT_ACTIVATION_MATRIX.md +10 -6
  20. package/core/tera-system/AGENT_DEPENDENCY_MAP.md +9 -7
  21. package/core/tera-system/AGENT_GENERATION_TEMPLATE.md +6 -5
  22. package/core/tera-system/AGENT_PERMISSION_MODEL.md +26 -9
  23. package/core/tera-system/TERA_AGENT_CONDUCT.md +17 -0
  24. package/core/tera-system/TERA_DISTRIBUTION_POLICY.md +1 -1
  25. package/core/tera-system/TeraPolicyMap.md +4 -2
  26. package/core/tera-system/TeraPreExecutionGate.md +34 -0
  27. package/core/tera-system/TeraPreparationDocumentationGovernance.md +21 -15
  28. package/core/tera-system/TeraSubAgents.md +2 -1
  29. package/core/tera-system/TeraSystemMaintenanceChecklist.md +12 -0
  30. package/core/tera-system/client-helpers/tera-client-engagement-gates.md +2 -2
  31. package/core/tera-system/client-helpers/tera-client-engagement-pricing.md +1 -1
  32. package/core/tera-system/client-helpers/tera-client-engagement-protocols.md +14 -9
  33. package/core/tera-system/engineering-helpers/database-privileges.md +63 -0
  34. package/core/tera-system/engineering-helpers/engineering-agent-core.md +11 -0
  35. package/core/tera-system/profiles/rust.md +1 -0
  36. package/core/tera-system/runtime/AGENT_SELF_ORIENTATION_PROTOCOL.md +1 -1
  37. package/core/tera-system/runtime/TERA_COMMAND_PROTOCOL.md +86 -0
  38. package/core/tera-system/runtime/TERA_RUNTIME_PROTOCOLS_CORE.md +14 -0
  39. package/core/tera-system/runtime/TERA_SOLUTION_PREPARATION_PROTOCOL.md +2 -2
  40. package/core/tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md +9 -2
  41. package/package.json +2 -2
@@ -21,7 +21,7 @@
21
21
 
22
22
  ---
23
23
 
24
- ## 1. هرم الصلاحيات (من الأضعف إلى الأقوى)
24
+ ## 1. حزم الصلاحيات (Permission Bundles — غير متوارثة) — SCP-2026-09-24-001
25
25
 
26
26
  ```
27
27
  ┌─────────────────────┐
@@ -65,7 +65,7 @@
65
65
  └─────────────────────┘
66
66
  ```
67
67
 
68
- الصلاحية الأعلى تشمل الصلاحيات الأدنى (إلا إذا نص على غير ذلك).
68
+ **تصحيح اتساق (SCP-2026-09-24-001):** ما يظهر أعلاه **خريطة مرجعية للحزم** وليس سلماً متوارثاً. لا تشمل أي حزمة صلاحيات حزمةً أخرى تلقائياً — كل حزمة تُمنح صراحةً عند الحاجة (Least Authority). مثال: `WRITE_CODE` تسمح بالكود وتمنع سجلات التحكم، و`WRITE_CONTROL` تسمح بسجلات التحكم وتمنع الكود — لا إحداهما تتضمن الأخرى. قد يُمنح العميل **أكثر من حزمة** عند الحاجة الفعلية (مثل `WRITE_CONTROL` + `WRITE_DOCS` لـ TeraAgent) وتُسجَّل. الصلاحية الفعّالة محكومة دائماً بالدور + المهمة + `Allowed Write Targets` + البيئة + الأدوات + الموافقات؛ ولا تلغي أي حزمة قيداً على مستوى الدور. المفهوم المهيمن هو: كل عميل يحصل على **مجموعة القدرات التي يحتاجها فقط**، لا رتبة في سلم.
69
69
 
70
70
  ---
71
71
 
@@ -183,7 +183,7 @@
183
183
  | كتابة ملفات تحضير | ❌ ممنوع |
184
184
  | كتابة ملفات تحكم | ❌ ممنوع |
185
185
  | تعديل project-control | ❌ ممنوع |
186
- | DEPLOY | ❌ ممنوع بدون موافقة إضافية |
186
+ | DEPLOY / النشر | ❌ ممنوع — النشر ملك `DevOpsDeploymentAgent` فقط (فصل المهام). لا يُرفع EngineeringAgent إلى `DEPLOY_WITH_APPROVAL` (SCP-2026-09-24-001) |
187
187
 
188
188
  **متى يستخدم:** لـ EngineeringAgent وأي عميل تنفيذي.
189
189
 
@@ -193,7 +193,8 @@
193
193
 
194
194
  | البند | القيمة |
195
195
  |---|---|
196
- | كل صلاحيات WRITE_CODE | ✅ |
196
+ | عمليات الكود اللازمة للنشر فقط (بناء/حزم/سكربتات نشر) — ضمن `Allowed Write Targets` | ✅ |
197
+ | سجلات التحكم/التوثيق (`project-control`, `tera-system`) | ❌ ممنوع — الحزمة **لا تُورّث** صلاحيات أخرى |
197
198
  | نشر على بيئة | ✅ بعد موافقة صريحة |
198
199
  | تعديل CI/CD | ✅ بعد موافقة صريحة |
199
200
  | تغيير إعدادات بيئة | ✅ بعد موافقة صريحة |
@@ -204,6 +205,19 @@
204
205
 
205
206
  ---
206
207
 
208
+ ### 2.9 صلاحيات النطاق الأمني (Security-Scoped Permissions)
209
+
210
+ > حزم تُمنح لأدوار فريق الحماية فقط، بحدود صارمة (SCP-2026-09-02-001 + SCP-2026-09-24-001).
211
+
212
+ | الحزمة | تُمنح لـ | الحدود |
213
+ |---|---|---|
214
+ | `EXECUTE_ATTACKS` | `red-team-agent` (الشبح) | ضمن `00_AUTHORIZATION.md` فقط — لا هجوم خارج نطاق التفويض، ولا على production بلا تفويض مكتوب |
215
+ | `WRITE_EVIDENCE` | أدوار الأمن (الشبح/العين/القاضي) | داخل `security-reports/` فقط — فصل كتابة صارم (كل دور يكتب مساحته) |
216
+
217
+ > **ملاحظة:** `READ_WRITE` المذكور في §4.3 هو **وضع أداة** (مثل Structurizr لملفات `.dsl`) وليس حزمة صلاحيات عميل.
218
+
219
+ ---
220
+
207
221
  ## 3. مصفوفة الصلاحية الافتراضية لكل عميل
208
222
 
209
223
  ### 3.1 العملاء الأساسيون (الـ 25 الرسميون)
@@ -218,10 +232,12 @@
218
232
  | engineering-agent-typescript | `ENGINEERING_AGENT_TS` | `WRITE_CODE` | — | كود TypeScript/Node.js/React وظيفي |
219
233
  | engineering-agent-phaser | `ENGINEERING_AGENT_PHASER` | `WRITE_CODE` | — | كود Phaser 3 Web Games |
220
234
  | engineering-agent-dotnet | `ENGINEERING_AGENT_DOTNET` | `WRITE_CODE` | — | كود .NET/C# |
235
+ | engineering-agent-flutter | `ENGINEERING_AGENT_FLUTTER` | `WRITE_CODE` | — | كود Flutter/Dart (عميل موبايل) — SCP-2026-09-23-006 |
236
+ | engineering-agent-django | `ENGINEERING_AGENT_DJANGO` | `WRITE_CODE` | — | كود Python/Django/DRF (خادم) — SCP-2026-09-23-006 |
221
237
  | ui-designer | `UI_VISUAL_DESIGNER_AGENT` | `WRITE_DOCS` | إلى READ_ONLY إذا كان مراجعة فقط | يكتب Design Tokens / Component Rules / Layout Rules داخل `28_UI_UX_GUIDELINES.md` |
222
238
  | tera-software-designer | `SOFTWARE_DESIGNER_AGENT` | `WRITE_DOCS` | إلى `PLAN_ONLY` إذا ما زالت الخطة غير ناضجة | يجهز Technical Specification للمهام فقط |
223
239
  | qa-agent | `QA_ACCEPTANCE_AGENT` | `RUN_TESTS` | إلى READ_ONLY إذا كان مراجعة فقط | **Planning Mode:** `WRITE_DOCS` — خطط الاختبار ومعايير القبول. **Execution Mode:** `RUN_TESTS` + bash — تشغيل CLI + تقارير اختبار رسمية |
224
- | auditor | `AUDITOR` | `READ_ONLY` | إلى `WRITE_DOCS` عند كتابة تقرير التدقيق | تدقيق Diff-first بعد التنفيذ؛ لا يعدّل كوداً |
240
+ | auditor | `AUDITOR` | `READ_ONLY` | إلى `WRITE_DOCS` عند كتابة تقرير التدقيق | تدقيق Diff-first بعد التنفيذ؛ لا يعدّل كوداً. + وضع `Preparation-Review` (قراءة فقط · تقرير) بطلب مُهندس — SCP-2026-09-24-006 |
225
241
  | design-reviewer | `DESIGN_REVIEWER` | `READ_ONLY` | إلى `WRITE_DOCS` عند تقرير المراجعة | مراجعة بصرية مستقلة؛ لا يبني ولا يعدّل |
226
242
  | monitor | `MONITOR` | `READ_ONLY` | إلى `WRITE_DOCS` عند تقارير الامتثال | يراقب الامتثال؛ يستدعي auditor بطلب Majed |
227
243
  | tera-client-engagement | `TCEA` | `WRITE_DOCS` (ضمن client/) | — | Discovery + Scoping + Proposals للعملاء الخارجيين |
@@ -274,12 +290,13 @@
274
290
  2. يتم توثيق رفع الصلاحية في `TASK-ID` أو `DECISIONS_LOG.md`.
275
291
  3. الرفع يكون للمهمة الحالية فقط (لا يصبح دائمًا).
276
292
 
277
- مثال:
293
+ مثال (مُصحَّح — SCP-2026-09-24-001):
278
294
  ```
279
- EngineeringAgent يبدأ بـ WRITE_CODE
280
- Tera يحتاجه لنشر fix عاجل → يرفع إلى DEPLOY_WITH_APPROVAL
281
- بعد النشر → يعود إلى WRITE_CODE
295
+ EngineeringAgent ينفّذ الإصلاح بـ WRITE_CODE (بناء + اختبار محلي فقط)
296
+ → إن لزم نشر: Tera يفوّض DevOpsDeploymentAgent (DEPLOY_WITH_APPROVAL + موافقة صريحة لكل عملية)
297
+ → لا يُرفع EngineeringAgent إلى DEPLOY_WITH_APPROVAL — من يكتب الكود لا ينشره (Separation of Duties)
282
298
  ```
299
+ > الاستعجال ليس استثناءً من الموافقات — لا نشر بلا تفويض DevOps + موافقة صريحة لكل عملية.
283
300
 
284
301
  ### 4.2 خفض الصلاحية
285
302
 
@@ -79,6 +79,23 @@ Decision needed from Majed or Tera:
79
79
 
80
80
  No hidden continuation is allowed after that point.
81
81
 
82
+ ### 5.1 STOP Semantics — Freeze Writes, Continue Safe Discovery (SCP-2026-09-24-005)
83
+
84
+ `STOP` means **freeze writes**, not "halt all investigation":
85
+
86
+ ```text
87
+ STOP WRITES
88
+ → read-only impact scan (same task scope, no writes)
89
+ → collect ALL related conflicts (not only the first)
90
+ → return ONE complete STOP packet
91
+ ```
92
+
93
+ - **No write** of any kind while stopped.
94
+ - Discovery stays **read-only** and within the task scope.
95
+ - Return **one complete** STOP packet listing all related conflicts → fewer `STOP → decision → STOP` round-trips.
96
+ - If a safe read-only scan is impossible, return the first STOP immediately (do not guess).
97
+ - This **never** weakens authority limits, scope control, or approval gates.
98
+
82
99
  ## 6. Task Completion Check
83
100
 
84
101
  After completing a meaningful task or tool-backed action, the agent should confirm internally — and explicitly when governance-sensitive — that:
@@ -64,7 +64,7 @@ Release Package (ملفات Tera-managed + SHA256SUMS + TERA_RELEASE_MANIFEST.js
64
64
 
65
65
  | الحزمة | الاسم (npm) | الإصدار الحالي | الوصف | الملفات الموزعة ضمن الحزمة |
66
66
  |---|---|---|---|---|
67
- | core | `@tera-system/core` | 0.4.0 | OpenCode Plugin — core governance (25 agents, 37 commands, distribution tools, security team) | `agents/`, `commands/`, `core/`, `assets/`, `tools/`, `scripts/` |
67
+ | core | `@tera-system/core` | 0.4.0 | OpenCode Plugin — core governance (25 agents, 38 commands, distribution tools, security team) | `agents/`, `commands/`, `core/`, `assets/`, `tools/`, `scripts/` |
68
68
  | pro | `@tera-system/pro` | 0.2.26 | Commercial edition — signed bundle + license gate + heartbeat | `scripts/`, `core/project-control`, `MANIFEST.json`, `opencode.tera.example.json`, `WELCOME.md`, `README.md` |
69
69
 
70
70
  **مستودع الحزم:** `https://github.com/Alabasi1980/Teranoo-System` — حزمتا npm + الـ bundle الموقّع (بناء ونشر فقط؛ لا محتوى يدوي).
@@ -49,10 +49,11 @@ Project files record project-specific decisions.
49
49
  | Phase 5 execution planning outputs | `tera-system/runtime/TERA_RUNTIME_TEMPLATES_DELIVERY.md` Sections 29-31 | `.opencode/agents/tera.md`, `TERA_RUNTIME_CHECKLISTS.md`, `TeraPreExecutionGate.md` | Produces `PROJECT_MASTER_PLAN.md`, `PROJECT_DETAILED_EXECUTION_PLAN.md`, and `EXECUTION_BATCH_PLAN.md`. Split notice INS-02: Sections 29-31 moved to DELIVERY file. |
50
50
  | Phase 6 post-execution review template | `tera-system/runtime/TERA_RUNTIME_TEMPLATES_DELIVERY.md` Section 32 | `TASK_TEMPLATE.md`, `TeraPreExecutionGate.md`, `TERA_RUNTIME_CHECKLISTS.md` | Used inside `TASK-COD-*` before final acceptance or closure. Note: `TASK_TEMPLATE.md` lives at `project-control/tasks/TASK_TEMPLATE.md` (clarified INS-07, 2026-08-01). Split notice INS-02: Section 32 moved to DELIVERY file. |
51
51
  | Phase 7 delivery, handover, and closure | `.opencode/agents/tera.md` Section 5 + `TERA_RUNTIME_TEMPLATES_DELIVERY.md` Section 35 | `.opencode/agents/tera.md`, `TERA_RUNTIME_CHECKLISTS.md`, `TERA_RUNTIME_PROTOCOLS.md` | Project closure is separate from last TASK-COD closure. Phase 7 does not execute code. Split notice INS-02: Section 34 moved to DELIVERY file. |
52
- | Sub-agent registry (core) | `tera-system/TeraSubAgents.md` | `.opencode/agents/tera.md` | Core agents (Engineering, QA, Auditor, Software Designer) — 769 lines 🟢 |
53
- | Sub-agent registry (helpers) | `tera-system/TeraHelperAgents.md` | `.opencode/agents/tera.md` | Helper agents (Security, DevOps, Domain, ERP, etc.) — 964 lines 🟢 — split from TeraSubAgents.md via SCP-2026-07-26 |
52
+ | Sub-agent registry (core) | `tera-system/TeraSubAgents.md` | `.opencode/agents/tera.md` | Core agents (Engineering, QA, Auditor, Software Designer) — المصدر الحي هو `.opencode/agents/` (لا يُعتمد عدّاد سطور ثابت) |
53
+ | Sub-agent registry (helpers) | `tera-system/TeraHelperAgents.md` | `.opencode/agents/tera.md` | Helper agents (Security, DevOps, Domain, ERP, etc.) — split from TeraSubAgents.md via SCP-2026-07-26 (لا يُعتمد عدّاد سطور ثابت) |
54
54
  | Agent generation template | `tera-system/AGENT_GENERATION_TEMPLATE.md` | `TERA_RUNTIME_PROTOCOLS_CORE.md` | Draft agents use this source. |
55
55
  | Pre/Post execution gates | `tera-system/TeraPreExecutionGate.md` | `.opencode/agents/tera.md`, `TERA_RUNTIME_PROTOCOLS_CORE.md` | Gate details stay in the policy file. |
56
+ | Quick-command layer protocol | `tera-system/runtime/TERA_COMMAND_PROTOCOL.md` | `.opencode/commands/` (كل الأوامر تُحيل إليه) | Workspace Resolution (§1) · Closure Prerequisites (§3) · Closure Transaction (§4) · Command Conformance (§5). SCP-2026-09-24-002. |
56
57
  | Token/context policy | `tera-system/TeraTokenPolicy.md` | `.opencode/agents/tera.md` | Runtime contains only startup/loading rules. |
57
58
  | Runtime protocols | `tera-system/runtime/TERA_RUNTIME_PROTOCOLS_CORE.md` + `TERA_RUNTIME_PROTOCOLS_CLIENT.md` | `.opencode/agents/tera.md` | Detailed operational behavior. Split INS-02 continuation: core (1–11) + client (12–18) + knowledge (19). |
58
59
  | Client Discovery protocol | `tera-system/runtime/CLIENT_DISCOVERY_PROTOCOL.md` | `TERA_RUNTIME_PROTOCOLS_CLIENT.md` (Section 18 → reference) | Extracted from §18 of Runtime Protocols; covers full Discovery and Smart Interview. |
@@ -95,6 +96,7 @@ Project files record project-specific decisions.
95
96
  | System maintenance | `tera-system/TeraSystemMaintenanceChecklist.md` | `.opencode/agents/tera.md` | Use when modifying Tera itself. |
96
97
  | Agent dependency map | `tera-system/AGENT_DEPENDENCY_MAP.md` | `tera-system/AGENT_DEPENDENCY_MAP.md` | Cross-references between agent files; safe edit order; file size alerts. Read before editing any agent file. |
97
98
  | Engineering agent core | `tera-system/engineering-helpers/engineering-agent-core.md` | `.opencode/agents/engineering-agent.md`, `.opencode/agents/engineering-agent-dotnet.md` | Shared engineering rules for ALL engineering agents. Must be read before every task. |
99
+ | DB privilege feasibility & probe hygiene | `tera-system/engineering-helpers/database-privileges.md` | `TeraPreExecutionGate.md` §5.1 | ميكانيكا PG: runtime principal/role · GRANT/SET ROLE · probe hygiene (42501/25P02) · least-privilege. SCP-2026-09-24-005. |
98
100
  | .NET Engineering agent | `.opencode/agents/engineering-agent-dotnet.md` | `tera-system/TeraSubAgents.md`, `tera-system/AGENT_ACTIVATION_MATRIX.md`, `tera-system/AGENT_DEPENDENCY_MAP.md` | Specialized .NET/C# engineering agent. Used for .NET tasks instead of the general engineering-agent.md. |
99
101
  | Scenario stress tests | `tera-system/TeraScenarioStressTests.md` | Not applicable | Used for validation, not daily runtime. |
100
102
  | Client workspace guide | `clients/README.md` | Not applicable | Folder usage guide only; policies remain in `tera-system/`. |
@@ -225,6 +225,40 @@ BLOCKED
225
225
 
226
226
  ---
227
227
 
228
+ ### 5.1 Empirical Feasibility & Environment Gates (SCP-2026-09-24-005 — Risk-Based)
229
+
230
+ > **المبدأ:** لا تُثبّت قراراً حسّاساً اعتماداً على التوثيق/الاستنتاج وحده إن كان **probe صغير رخيص ممكن**.
231
+ > القاعدة **risk-based** — لا تحوّل كل قرار صغير إلى مختبر.
232
+
233
+ ```text
234
+ Low → source inspection
235
+ Medium → source inspection + targeted static check
236
+ High → + inventory (كل المواضع المحتملة)
237
+ Critical → + live capability probe (بالدور/البيئة الحقيقية حيث أمكن)
238
+ ```
239
+
240
+ **(أ) EMPIRICAL-BEFORE-PIN** — أي قرار يثبّت: تبعية · schema head · صلاحية DB · قدرة دور · قدرة toolchain · حزمة خارجية
241
+ → لا يُعتمد من الاستنتاج وحده؛ استخدم `reasoning + source inspection + focused probe` (رخيص وفقط عند الاقتصاد).
242
+
243
+ **(ب) DB Runtime Privilege Feasibility** — عند مهمة تلمس قاعدة بيانات حسّاسة أو separation (role separation · RLS · WORM · privileged writer · reader/writer split · audit/security tables · service principals · least-privilege):
244
+ ```text
245
+ New query/operation → production component → runtime principal → required privileges → actual grants
246
+ ```
247
+ تأكد أن **الدور الفعلي في الإنتاج** يملك الصلاحية — لا مجرد وجود الجدول/الأعمدة/الدور. الميكانيكا: `tera-system/engineering-helpers/database-privileges.md`.
248
+
249
+ **(ج) Schema-Head / Cross-Pin Inventory** — عند إضافة Migration أو تغيير رقم/رأس الـSchema:
250
+ قبل التفويض التالي، نفّذ **جرداً شاملاً** لكل مواضع التثبيت المحتملة (لا فقط موضع الفشل الأول):
251
+ `MIGRATION_HEAD · EXPECTED_HEAD · migration count · == old_head · 1..=old_head · old_head:true · fixtures · startup guards · error messages · test names · provisioning scripts`.
252
+
253
+ **(د) Environment-aware Execution** — قبل اختبار يعتمد على قدرة بيئية (شاشة تفاعلية · Docker · أداة CLI · جهاز):
254
+ 1. Preflight: اكتشف القدرة البيئية. 2. شغّل الاختبار. 3. صنّف بدقّة:
255
+ - `CODE_REGRESSION` (فشل حقيقي → لا قبول) · `ENVIRONMENT_NOT_AVAILABLE` (قدرة غائبة → موثّق، **ليس PASS**، وليس فشل كود).
256
+ > ممنوع تحويل Environment Failure إلى `PASS` كاذب، وممنوع رفض كود سليم بسبب بيئة غائبة.
257
+
258
+ **(هـ) تعزيز Paired Records** — عند حدث حوكمي يجب أن يظهر في **Audit Trail + Activity Log** معاً (SCP-2026-09-24-005): حدّثهما مقترنَين (راجع Cross-Record Consistency §6.2) — لا تنتظر اكتشاف المالك لنقص لاحقاً.
259
+
260
+ ---
261
+
228
262
  ## 6. قواعد منع تضخم المهمة
229
263
 
230
264
  يمنع داخل أي مهمة تنفيذية إضافة أي عنصر غير مطلوب صراحة في عنوان المهمة أو معايير قبولها.
@@ -121,14 +121,14 @@ Every preparation document passes through these states. Not all states are manda
121
121
 
122
122
  | State | Meaning | Who Can Advance | Consumption Allowed By |
123
123
  |---|---|---|---|
124
- | **Draft** | Being written; content may be incomplete | Maker agent + Tera | No consumer agent |
125
- | **Under Cross-Review** | Submitted for cross-document review by Checker agent(s) | Tera submits; Checker returns findings | Reviewers only |
126
- | **Module Baseline Approved** | A defined module/wave of this document is approved for that module | Tera → Owner (for sensitive items only) | SoftwareDesignerAgent for that module; execution planning for that module |
127
- | **System Pending Integration** | Approved at module level but not yet reconciled with all system-level documents | Tera | Limited: execution planning for the module only |
128
- | **System Approved** | All modules approved; system-level consistency confirmed | Tera → Owner (summary only) | All consumer agents; full execution planning |
124
+ | **Draft** | Being written; content may be incomplete | Maker agent + Orchestrator (مُهندس) | No consumer agent |
125
+ | **Under Cross-Review** | Submitted for cross-document review by Checker agent(s) | Orchestrator (مُهندس) submits; Checker returns findings | Reviewers only |
126
+ | **Module Baseline Approved** | A defined module/wave of this document is approved for that module | Orchestrator (مُهندس) → Owner (for sensitive items only) | SoftwareDesignerAgent for that module; execution planning for that module |
127
+ | **System Pending Integration** | Approved at module level but not yet reconciled with all system-level documents | Orchestrator (مُهندس) | Limited: execution planning for the module only |
128
+ | **System Approved** | All modules approved; system-level consistency confirmed | Orchestrator (مُهندس) → Owner (summary only) | All consumer agents; full execution planning |
129
129
  | **Locked** | No further changes expected; only Change Request can reopen | Owner | All consumers (read-only) |
130
- | **Change Requested** | Formal change requested after baseline; impact analysis required | Owner → Tera | Only the impact analysis |
131
- | **Superseded** | Replaced by a newer version of the same document | Tera | None (read archived copy only) |
130
+ | **Change Requested** | Formal change requested after baseline; impact analysis required | Owner → Orchestrator (مُهندس) | Only the impact analysis |
131
+ | **Superseded** | Replaced by a newer version of the same document | Orchestrator (مُهندس) | None (read archived copy only) |
132
132
 
133
133
  ### 3.2 Closure Conditions
134
134
 
@@ -150,7 +150,7 @@ Every preparation document passes through these states. Not all states are manda
150
150
  | Role | Who | Responsibility |
151
151
  |---|---|---|
152
152
  | **Maker** | Preparation role performed by `application-blueprint` or a generated helper agent (prep roles: RequirementsScope / BusinessWorkflow / DataDesign / UIUXStructure / SolutionArchitecture) | Writes the document following its template and assigned allowed-write-targets |
153
- | **Checker** | A different preparation agent or coordination agent | Reviews the document for: cross-document consistency, dependency alignment, completeness against its template |
153
+ | **Checker** | A different preparation agent, or `auditor` in **`Preparation-Review`** mode (SCP-2026-09-24-006 — batch-level, read-only) | Reviews the document for: cross-document consistency, dependency alignment, completeness against its template |
154
154
  | **Orchestrator** | ApplicationBlueprintAgent (مُهندس) — SCP-2026-07-28-118 | Plans the document, assigns Maker, assigns Checker, tracks state, detects contradictions, prepares approval packages |
155
155
  | **Owner** | Majed | Approves only sensitive decisions (module boundaries, scope changes, critical Cross-Cutting Rules, System Approved promotion). Does not review every field. |
156
156
 
@@ -163,7 +163,9 @@ Every preparation document passes through these states. Not all states are manda
163
163
  - Completeness against the document's own required sections (from the template)
164
164
  - Edge cases and missing dependencies
165
165
  4. If the Checker finds issues, the document returns to `Draft` with documented findings.
166
- 5. If the Checker approves, Tera advances it to the next state.
166
+ 5. If the Checker approves, the Orchestrator (مُهندس) advances it to the next state.
167
+ 6. **Self-review ≠ Independent Cross-Review (SCP-2026-09-24-004):** if Maker and Checker are the same logical role, evidence MUST be labeled `Review Type: SELF_REVIEW` + `Independent Review: NOT PERFORMED` + reason. Never label it "Cross-Review PASS" — a downstream reader (Tera/Auditor) would misread it as second-party review.
168
+ 7. **Preparation Review Classification:** every batch declares exactly one: `INDEPENDENT_CHECK_REQUIRED` (default for Medium+) · `SELF_REVIEW_ALLOWED_WITH_OWNER_WAIVER` (Tiny/Low-risk only — explicit owner waiver + honest labeling) · `SPECIALIST_REVIEW_REQUIRED`. Waiver is explicit, never assumed. See §9.
167
169
 
168
170
  ### 4.3 Owner Approval Points
169
171
 
@@ -181,6 +183,8 @@ The Owner (Majed) approves only these decision points:
181
183
  - Routine updates after initial baseline (unless the update changes scope or cross-cutting rules)
182
184
  - Checker findings or routine state transitions
183
185
 
186
+ > **No-Silence-Approval Rule (SCP-2026-09-24-004):** a material preparation decision/assumption is **never** accepted by silence or by wording like "accepted unless the owner objects". Until explicit owner confirmation it stays `Proposed / Pending Owner Confirmation` and must NOT enter the baseline or Handoff. **Silence ≠ approval.**
187
+
184
188
  ---
185
189
 
186
190
  ## 5. Partial Approval / Module Baseline
@@ -202,7 +206,7 @@ Large projects may have multiple modules (e.g., Inventory, Sales, HR). Each modu
202
206
  ### 5.3 Cross-Module Consistency
203
207
 
204
208
  Before advancing to `System Approved`:
205
- 1. Tera orchestrates a **system-level reconciliation check**:
209
+ 1. The Orchestrator (مُهندس) runs a **system-level reconciliation check**:
206
210
  - No duplicate entities across modules
207
211
  - Consistent naming and relationships
208
212
  - No orphan references (e.g., a screen that refers to a removed entity)
@@ -240,8 +244,8 @@ Open Questions: [any unresolved questions before approval]
240
244
 
241
245
  | Change Severity | Approval Required |
242
246
  |---|---|
243
- | Addition within existing scope (no breaking change) | Tera (recorded in `CHANGE_REQUESTS.md`) |
244
- | Modification affecting cross-module consistency | Tera + Owner (summary only) |
247
+ | Addition within existing scope (no breaking change) | Orchestrator (مُهندس) (recorded in `CHANGE_REQUESTS.md`) |
248
+ | Modification affecting cross-module consistency | Orchestrator (مُهندس) + Owner (summary only) |
245
249
  | Deletion or deprecation of existing content | Owner |
246
250
  | Change affecting architecture, security, or compliance | Owner |
247
251
 
@@ -263,7 +267,7 @@ Targeted web research is permitted **only** when all of the following are true:
263
267
  - **Gap Description**: what is missing and why it is needed
264
268
  - **Research Question**: a single, precise question
265
269
  - **Source Criteria**: what kind of sources are acceptable
266
- 2. Tera or `DomainResearchAgent` executes the search.
270
+ 2. The Orchestrator (مُهندس) or `DomainResearchAgent` executes the search.
267
271
  3. The result is documented as:
268
272
 
269
273
  ```text
@@ -324,11 +328,13 @@ SoftwareDesignerAgent:
324
328
  For small projects (as classified in `TERA_PROJECT_DECISION.md`):
325
329
 
326
330
  - The full lifecycle may be simplified: `Draft` → `System Approved` → `Locked`, skipping intermediate states
327
- - Cross-review may be done by Tera itself rather than a separate Checker agent
328
331
  - Partial baselines are not needed (single module)
329
332
  - The Owner may approve a single bulk approval instead of per-decision-point approvals
333
+ - **Review independence (مُصحَّح — SCP-2026-09-24-004):** لا يُستخدم "Tera نفسه كـChecker" (معمارية قديمة — Tera الآن Phases 5–7 فقط، ولا يشارك في تحضير Phases 1–4). بدلاً من ذلك:
334
+ - **الافتراضي:** Checker مستقل — **`auditor` في وضع `Preparation-Review`** (كل دفعة · قراءة فقط · اتساق مستندات) — SCP-2026-09-24-006.
335
+ - **Tiny / Low-risk فقط:** `SELF_REVIEW_ALLOWED_WITH_OWNER_WAIVER` — مراجعة ذاتية **بتصنيف صريح `SELF_REVIEW`** + تنازل مالك صريح، **ولا تُسمّى Cross-Review مستقلاً**.
330
336
 
331
- The project classification determines which simplification applies. The governance model is not bypassed — it is scaled.
337
+ The project classification determines which simplification applies. The governance model is not bypassed — it is scaled. **استقلال المراجعة لا يُدّعى بغير دليل.**
332
338
 
333
339
  ---
334
340
 
@@ -141,6 +141,7 @@ Auditor (مُدقق) هو عميل جودة فرعي، وليس عميلاً ر
141
141
  المستدعون المصرح لهم في v1:
142
142
  1. TeraAgent — بعد مهام التنفيذ وفق قرار Auditor Review Decision.
143
143
  2. Monitor — فقط عندما يطلب Majed من Monitor تحدي أو التحقق من عمل Tera بجودة مستقلة.
144
+ 3. ApplicationBlueprintAgent (مُهندس) — **مراجعة تحضير فقط** (Phases 1–4): وضع `Preparation-Review` (كل دفعة · قراءة فقط · اتساق مستندات) — SCP-2026-09-24-006. لا صلاحية تصميم/نطاق/قبول.
144
145
 
145
146
  الشروط:
146
147
  1. التفويض يجب أن يكون مرتبطاً بمهمة/دفعة محددة.
@@ -277,7 +278,7 @@ but the generic sub-agent registry in `TeraSubAgents.md` must remain stack-neutr
277
278
 
278
279
  # 5. العملاء الأساسيون — السجل الرسمي (25 عميلاً)
279
280
 
280
- > **مصدر الحقيقة:** `.opencode/agents/` — 23 ملفاً نشطاً بالأسماء الحديثة. هذا القسم **سجل مرجعي موجز**؛ التفاصيل التشغيلية الكاملة لكل عميل في ملفه الخاص.
281
+ > **مصدر الحقيقة:** `.opencode/agents/` — **25 ملفاً نشطاً** بالأسماء الحديثة (القائمة الفعلية أوثق من أي عدّاد). هذا القسم **سجل مرجعي موجز**؛ التفاصيل التشغيلية الكاملة لكل عميل في ملفه الخاص.
281
282
  > **التصنيف الرسمي:** 8 Coding + 3 Quality + 2 Management + 4 Engagement + 2 Research + 1 Knowledge + 1 Specialist + 1 System + 3 Security = **25 عميلاً**.
282
283
 
283
284
  ---
@@ -66,6 +66,18 @@ Before finishing, verify:
66
66
  - Is the runtime file becoming a full manual?
67
67
  - Are client-facing rules duplicated outside client policies without need?
68
68
 
69
+ ## 5.1 Registration Consistency Check (SCP-2026-09-24-001)
70
+
71
+ عند أي تغيير يمس عميلاً أو صلاحية أو تفعيلاً، شغّل **المُدقّق المعتمد** (يُرجع PASS/FAIL + مسار الدليل):
72
+
73
+ ```text
74
+ node scripts/validate-governance.mjs
75
+ ```
76
+
77
+ يتحقق من: كل ملف في `.opencode/agents/` له مدخل واحد في `TeraSubAgents.md` §5، `AGENT_ACTIVATION_MATRIX.md` §2.1، `AGENT_PERMISSION_MODEL.md` §3.1، `AGENT_DEPENDENCY_MAP.md` · صفر ID مكرر · حزم/Triggers معرَّفة · `agent:` في أوامر التهيئة يشير لملف موجود.
78
+
79
+ - النتيجة: PASS / FAIL (مع القائمة). لا إغلاق بتقرير "PASS" بلا تشغيل فعلي.
80
+
69
81
  ## 6. Validation Commands
70
82
 
71
83
  Recommended checks:
@@ -253,6 +253,6 @@ Select-String -Path TERA_HANDOFF_PACKAGE.md -Pattern 'D-\d{3}' | ForEach-Object
253
253
  | **الاسم** | Hypercare Handoff Gate |
254
254
  | **الهدف** | ضمان استقرار النظام بعد الإطلاق قبل تسليمه نهائياً للفريق التشغيلي أو إغلاق المشروع |
255
255
  | **المدخلات المطلوبة** | `ISSUE_LOG.md`, `HANDOVER_DOCUMENT.md`, Post-Implementation Review |
256
- | **شروط النجاح** | 1. ISSUE_LOG.md — لا توجد مشاكل Critical/High مفتوحة<br>2. HANDOVER_DOCUMENT.md — يحتوي: كلمة السر، عناوين الخوادم، جهات الاتصال، إجراءات الصيانة الأساسية<br>3. Post-Implementation Review — أُجريت مع الزبون ووثّقت<br>4. TCEA يؤكد: الزبون راضٍ ولا توجد مشاكل معلقة |
257
- | **شروط الإيقاف (Blocking Conditions)** | 1. مشاكل Critical/High مفتوحة ← توقف<br>2. HANDOVER_DOCUMENT.md غير مكتمل ← توقف |
256
+ | **شروط النجاح** | 1. ISSUE_LOG.md — لا توجد مشاكل Critical/High مفتوحة<br>2. HANDOVER_DOCUMENT.md — يحتوي: عناوين الخوادم، جهات الاتصال، إجراءات الصيانة الأساسية + **طريقة تسليم بيانات الاعتماد (مرجع فقط — لا قيم): vault/password-manager/قناة آمنة + Secret ID/مالكه**<br>3. Post-Implementation Review — أُجريت مع الزبون ووثّقت<br>4. TCEA يؤكد: الزبون راضٍ ولا توجد مشاكل معلقة<br>⚠️ **ممنوع منعاً باتاً تضمين أي كلمة سر/توكن/مفتاح فعلي في الملف** (TeraClientPolicy: لا أسرار في ملفات العميل) — SCP-2026-09-24-003 |
257
+ | **شروط الإيقاف (Blocking Conditions)** | 1. مشاكل Critical/High مفتوحة ← توقف<br>2. HANDOVER_DOCUMENT.md غير مكتمل ← توقف<br>3. تضمين أي قيمة اعتماد فعلية في HANDOVER_DOCUMENT.md ← توقف + إزالة فورية (خطر أمني P0) |
258
258
  | **الإخراج الإلزامي** | **PASS/FAIL** — عند PASS: إغلاق المشروع أو الانتقال إلى دعم عادي (Retainer) |
@@ -157,7 +157,7 @@ clients/CLIENT-*/applications/APP-*/client-engagement/
157
157
  ├── SCOPE_SUMMARY.md ← ملخص النطاق (للمشاريع المتوسطة)
158
158
  ├── FEATURE_LIST.md ← قائمة الميزات (للمشاريع المتوسطة+)
159
159
  ├── DRAFT_QUOTATION.md ← مسودة عرض السعر (Level 2)
160
- ├── TERA_HANDOFF_PACKAGE.md ← حزمة التسليم لـ Tera
160
+ ├── TERA_HANDOFF_PACKAGE.md ← حزمة التسليم لـ مُهندس (ApplicationBlueprintAgent) — الاسم تاريخي (Track A)
161
161
  ├── CLIENT_DECISION_LOG.md ← سجل القرارات
162
162
  └── CHANGE_REQUEST_LOG.md ← سجل طلبات التغيير
163
163
  ```
@@ -609,9 +609,10 @@ TCEA يكيِّف أسلوبه، ولا يتجاوز سياج الحوكمة أ
609
609
  2. قدّم الـ Demo في 3 مراحل:
610
610
  المرحلة 1 — السياق: "هذا المنتج مصمم لـ [المجال]، يغطي ميزات مثل [الميزات الرئيسية]"
611
611
  المرحلة 2 — الربط بالاحتياج: "أنت ذكرت أنك تحتاج X — المنتج يغطيها بـ Y"
612
- المرحلة 3 — القيمة: "هذا يوفر عليك [وقت/تكلفة] بـ [رقم/مثال]"
612
+ المرحلة 3 — القيمة: **بلا رقم غير موثّق** — إن لم يتوفر مصدر/افتراض موثّق فصياغة نوعية فقط
613
613
  3. لا تَعِد بميزات غير موجودة في Feature Matrix
614
614
  4. إذا سأل الزبون عن ميزة غير موجودة → سجّلها كـ Gap في FIT_GAP_MATRIX.md
615
+ 5. **قاعدة الأرقام (SCP-2026-09-24-003):** لا يُعرض ادّعاء كمّي (توفير/ROI/وقت/أداء/امتثال) للعميل إلا بمصدره وافتراضاته موثّقة؛ وإلا فصياغة نوعية فقط
615
616
  ```
616
617
 
617
618
  #### هيكل PRODUCT_DEMO_SCRIPT.md
@@ -646,7 +647,7 @@ TCEA يكيِّف أسلوبه، ولا يتجاوز سياج الحوكمة أ
646
647
  | التصنيف | المعنى | الإجراء | التكلفة |
647
648
  |:-------:|--------|---------|:-------:|
648
649
  | **Fit** ✅ | المنتج يغطي المطلب دون تعديل | لا شيء — يُسجّل كـ Covered | $0 |
649
- | **Gap-Config** 🔧 | يمكن تغطيته عبر إعدادات النظام فقط | تكوين (Configuration) — يديره المستشار | ضمن Fixed Price |
650
+ | **Gap-Config** 🔧 | يمكن تغطيته عبر إعدادات النظام فقط | TCEA يصنّفه/يوثّقه · **التنفيذ في B4 بيد الجهة المكلّفة (TeraAgent/فرق التنفيذ)** — TCEA لا ينفّذ التكوين | ضمن Fixed Price |
650
651
  | **Gap-Custom** 💻 | يتطلب تطويراً مخصصاً (RICEFW) | يُنشأ RICEFW Item — يُسعّر منفصلاً (T&M أو Fixed) | إضافي — خارج Fixed |
651
652
  | **Process Change** 🔄 | يمكن تغطيته بتعديل عملية الزبون | يُقنع الزبون بتعديل العملية — لا تطوير | $0 (ولكن يحتاج إدارة تغيير) |
652
653
 
@@ -654,7 +655,7 @@ TCEA يكيِّف أسلوبه، ولا يتجاوز سياج الحوكمة أ
654
655
 
655
656
  ```text
656
657
  1. Configuration-First: Gap-Config هو الحل الافتراضي دائماً (راجع B.3)
657
- 2. كل Gap-Custom يحتاج Business Case: "هل هذه الميزة تمنح ميزة تنافسية حقيقية؟"
658
+ 2. كل Gap-Custom يحتاج Business Case (يُقبل إذا أثبت **واحداً على الأقل**): ميزة تنافسية حقيقية · متطلب قانوني/تنظيمي · التزام تعاقدي · ضرورة تشغيلية بعائد/خفض خطر · تكامل إلزامي بلا بديل تكوين/طرف ثالث
658
659
  3. أولويات MoSCoW: صنّف كل مطلب حسب Must/Should/Could/Won't
659
660
  4. كل مطلب في FIT_GAP_MATRIX.md له: وصف، تصنيف، أولوية، إجراء مقترح، تقدير جهد
660
661
  ```
@@ -689,17 +690,21 @@ TCEA يكيِّف أسلوبه، ولا يتجاوز سياج الحوكمة أ
689
690
  Customization = الحل الأخير — وليس الأول.
690
691
  ```
691
692
 
692
- #### الأسئلة الثلاثة قبل أي تخصيص
693
+ #### معايير قبول التخصيص (Gap-Custom) — مُوسَّعة (SCP-2026-09-24-003)
693
694
 
694
- قبل الموافقة على أي `Gap-Custom`، أجب على هذه الأسئلة الثلاثة:
695
+ قبل الموافقة على أي `Gap-Custom`، يجب إثبات **واحد على الأقل** من أسس القبول:
695
696
 
696
697
  ```text
697
- 1. هل هذه الميزة تمنح الزبون ميزة تنافسية حقيقية؟ (وليس مجرد "نحبها كذا")
698
- 2. هل تكلفة التخصيص (تطوير + صيانة + اختبار ترقيات) تبرر العائد؟
699
- 3. هل يوجد بديل في النظام الحالي — أو إضافة معتمدة من السوق — يغطي نفس الاحتياج؟
700
- إذا الإجابة على أي سؤال = لا → التخصيص مرفوض. عُد إلى Configuration أو Process Change.
698
+ 1. ميزة تنافسية حقيقية (وليس "نحبها كذا")
699
+ 2. متطلب قانوني / تنظيمي / ضريبي
700
+ 3. التزام تعاقدي (Contractual requirement)
701
+ 4. ضرورة تشغيلية بعائد مثبت أو خفض خطر مادي
702
+ 5. تكامل إلزامي (مثل جهة حكومية) بلا بديل تكوين أو طرف ثالث
701
703
  ```
702
704
 
705
+ ثم — إن قُبل الأساس — قيّم دائماً: تكلفة دورة الحياة (تطوير + صيانة + اختبار ترقيات) · عبء الترقيات · أثر الدعم · الأثر الأمني. Financial ROI مطلوب فقط عندما يكون الأساس تجارياً، لا عندما يكون الأساس قانونياً/تعاقدياً إلزامياً.
706
+ Configuration-First يبقى المبدأ الافتراضي؛ لكن **لا يُرفض التخصيص تلقائياً** لمجرد غياب "ميزة تنافسية" إذا وُجد أساس إلزامي.
707
+
703
708
  #### قاعدة التوثيق
704
709
 
705
710
  كل `Gap-Custom` معتمد يجب أن يُوثّق في `RICEFW_INVENTORY.md` بالتفصيل:
@@ -0,0 +1,63 @@
1
+ # Database Privilege Feasibility & Probe Hygiene (Helper)
2
+
3
+ > **المصدر:** SCP-2026-09-24-005 — دعم `TeraPreExecutionGate §5.1` لمهام قاعدة البيانات الحسّاسة.
4
+ > **الحمولة العامة فقط** — لا أسماء/جداول/أدوار من أي مشروع عمّال (تُعمَّم كمفاهيم).
5
+
6
+ ## 1. متى يُحمَّل؟
7
+ عند أي مهمة تلمس قاعدة بيانات **حسّاسة** أو فيها **فصل صلاحيات/أدوار**: role separation · RLS · WORM/append-only · privileged writer · reader/writer split · جداول audit/security · service principals · least-privilege.
8
+
9
+ ## 2. سلسلة التحقق (Feasibility Chain)
10
+
11
+ ```text
12
+ New query/operation
13
+ → production component (من سينفّذه فعلاً؟)
14
+ → runtime principal/role (بأي هوية؟)
15
+ → required privileges (ماذا يحتاج الاستعلام؟)
16
+ → actual grants (ماذا يملك الدور فعلاً؟)
17
+ ```
18
+
19
+ **الفخّ المتكرر:** `query valid + schema valid + tests valid` — لكن **الدور الفعلي في الإنتاج لا يملك صلاحية التنفيذ** (يعمل في التطوير بـsuperuser فيمرّ).
20
+ → لا يكفي: existence (table/columns/role) — بل **privilege**.
21
+
22
+ ## 3. ميكانيكا PostgreSQL
23
+
24
+ | المفهوم | الأمر/الاستعلام |
25
+ |---|---|
26
+ | عرض صلاحيات دور | `\dp <table>` / `has_table_privilege('role','table','SELECT')` / `has_column_privilege('role','table','col','SELECT')` |
27
+ | منح أدنى | `GRANT SELECT (colA, colB) ON <table> TO <role>;` — **أعمدة محدّدة لا الجدول** |
28
+ | اختبار بالدور الحقيقي | `SET ROLE <runtime_role>; <query>; RESET ROLE;` |
29
+ | `insufficient_privilege` | **`42501`** — مطلوب (متوقّع في اختبار أنه **مرفوض**). |
30
+ | `in_failed_sql_transaction` | **`25P02`** — يظهر **بدل** الخطأ الحقيقي إن تابعتَ بعد أول فشل داخل نفس المعاملة. |
31
+
32
+ ## 4. Probe Hygiene (درس 318 — إلزامي)
33
+
34
+ ```text
35
+ ❌ عدة probes مستقلّة داخل معاملة واحدة:
36
+ أول failure (42501) يُجهض المعاملة → النتائج التالية تتحول إلى 25P02 (مضلِّلة)
37
+
38
+ ✅ معاملة/SAVEPOINT مستقلة لكل probe:
39
+ BEGIN; ... ; ROLLBACK; أو SAVEPOINT p; ... ; ROLLBACK TO p;
40
+ ```
41
+
42
+ - كل probe صلاحية **معزول** — لا تعتمد على نتيجة تالية بعد فشل.
43
+ - عند اختبار "يجب أن يُرفض" → أعد `RESET ROLE` + `ROLLBACK` قبل الـprobe التالي.
44
+ - سجّل `SQLSTATE` الحقيقي لكل probe (لا تخمّن).
45
+
46
+ ## 5. أدنى صلاحية (Least Privilege)
47
+
48
+ - امنح **الأعمدة/العمليات المطلوبة فقط** — لا الجدول كاملاً.
49
+ - مثال مبدأي: كاتب WORM يحتاج قراءة الحقل السابق لبناء السلسلة → يُمنح **فقط** أعمدة السلسلة اللازمة (مثل `seq, hash`)، **لا** `actor/action/payload/sig`.
50
+ - أي توسيع صلاحية إنتاج **يحتاج موافقة صريحة** (بوابة migrations/privileges).
51
+
52
+ ## 6. Evidence المطلوب في الـhandback
53
+
54
+ ```text
55
+ Runtime principal:
56
+ Required privileges:
57
+ Actual grants (probe result + SQLSTATE):
58
+ Least-privilege grant used:
59
+ Environment (PG version / role / DB):
60
+ ```
61
+
62
+ ## 7. المرجع
63
+ `TeraPreExecutionGate.md §5.1` — EMPIRICAL-BEFORE-PIN · DB Runtime Privilege Feasibility.
@@ -110,6 +110,17 @@ When writing integration tests that depend on external services:
110
110
  4. Keep container startup overhead reasonable: reuse containers across tests in the same suite where supported.
111
111
  5. Do not use Testcontainers for unit tests; reserve it for integration and E2E paths.
112
112
 
113
+ ### 6.2 Verify-Before-Assert (SCP-2026-09-24-005)
114
+
115
+ Before asserting anything as fact (in code, handback, commit, or decision):
116
+
117
+ - **Authoritative numeric constant** (schema head, migration count, expected count) → **fresh source read**, never from memory.
118
+ - **Long-file edit** → read the current file and build the **exact anchor** from fresh content (no memory anchors).
119
+ - **Commit / change claim** → verify the **actual content/diff** first; never claim a change you did not confirm.
120
+ - **"X exists / X is available"** → confirm it, or label `NOT VERIFIED`.
121
+
122
+ Do not fabricate; never claim a check passed that was not run (see §7).
123
+
113
124
  ---
114
125
 
115
126
  ## 7. Verification Discipline
@@ -70,6 +70,7 @@
70
70
  - **Parameterized queries إلزامي** — ممنوع string interpolation في SQL (SQL injection — OWASP).
71
71
  - `PgPool`: max_connections محدود (أقل من max Postgres ÷ عدد النسخ) + `acquire_timeout` + `idle_timeout` — لا إعدادات افتراضية.
72
72
  - Diesel/SeaORM: عند الحاجة — migrations عبر أدواتها الخاصة (`diesel_cli` / `sea-orm-cli`).
73
+ - **Schema-Head / Migration Pins (SCP-2026-09-24-005):** عند إضافة migration يغيّر رقم/رأس الـSchema، نفّذ **جرداً شاملاً** لكل مواضع التثبيت المحتملة (MIGRATION_HEAD · EXPECTED_HEAD · migration count · startup guards · fixtures · error messages · test names) **قبل التفويض التالي** — راجع `TeraPreExecutionGate §5.1 (ج)`.
73
74
 
74
75
  ## 7. CLI Side Effects
75
76
 
@@ -31,7 +31,7 @@
31
31
  - ما مصادر الحقيقة الخاصة بي؟
32
32
 
33
33
  5. **تأكد من فهم العلاقات:**
34
- - لا تفعّل أي عميل ولا تطلب تفعيلك ذاتياً (مالك التفعيل محدد في `TERA_RUNTIME_PROTOCOLS_CORE.md` §1).
34
+ - لا تفعّل أي عميل ولا تطلب تفعيلك ذاتياً (مالك التفعيل محدد في `AGENT_ACTIVATION_MATRIX.md` «القاعدة الحاكمة» وفي `TeraSubAgents.md` §1).
35
35
  - اعرف من يستدعيك (المالك / TeraAgent / عميل آخر) ومتى.
36
36
 
37
37
  ## إقرار الجاهزية (READINESS DECLARATION)
@@ -0,0 +1,86 @@
1
+ # TERA_COMMAND_PROTOCOL.md — بروتوكول طبقة الأوامر السريعة
2
+
3
+ > **المصدر:** SCP-2026-09-24-002 (معالجة Review 02 — Runtime/Orchestration).
4
+ > كل أمر في `.opencode/commands/` **يلتزم** بهذا الملف. الأوامر طبقة دخول — لا تتجاوز Runtime Core.
5
+
6
+ ---
7
+
8
+ ## 1. Workspace Resolution Gate (إلزامي قبل أي قراءة/كتابة)
9
+
10
+ كل أمر يحدّد المسارات أولاً — لا يستخدم مساراً نسبياً غامضاً:
11
+
12
+ ```text
13
+ ActiveAppPath = مسار التطبيق النشط
14
+ ProjectControlPath = <ActiveAppPath>/project-control/
15
+ ProjectPreparationPath = <ActiveAppPath>/project-preparation/
16
+ ```
17
+
18
+ **مصدر `ActiveAppPath` (بالترتيب):**
19
+ 1. `project-control/SYSTEM_ACTIVE_CONTEXT.md` الجذري إن وُجد (حقل `ActiveAppPath`).
20
+ 2. سياق الجلسة/الطلب الصريح من Majed.
21
+ 3. إن لم يتضح → **توقف واسأل**: "أي تطبيق/مشروع؟" — لا تفترض.
22
+
23
+ **قواعد:**
24
+ - لمشروع تطبيق/عميل: اقرأ/اكتب تحت `<ActiveAppPath>/project-control/` — **لا** الجذر.
25
+ - ملفات الجذر `project-control/` = **System Templates فقط** (وفق `tera.md` Tier 1).
26
+ - لا تعتمد على أن الجذر يحتوي `TASK_REGISTRY.md`/`PROJECT_ACTIVITY_LOG.md` — هذه خاصة بكل تطبيق.
27
+ - إن اختلف `HostRepoPath` (مستودع كود خارجي) عن مسار المنظومة → صرّح به منفصلاً.
28
+
29
+ ---
30
+
31
+ ## 2. Quick Command Principles
32
+
33
+ - الأوامر **تُشغّل** الـRuntime القائم؛ لا تعرّفه من جديد ولا تتجاوزه.
34
+ - لا تنفيذ بلا موافقة صريحة (Plan ≠ Build).
35
+ - لا تفترض حالةً غير موجودة في السجلات الرسمية؛ إن غابت → أخبر المالك.
36
+
37
+ ---
38
+
39
+ ## 3. Closure Prerequisites (إلزامي قبل `Accepted`/`Closed`)
40
+
41
+ لا يُغلق أي TASK إلا بعد استيفاء **كل** ما يلي (بالترتيب):
42
+
43
+ | # | الشرط | المرجع |
44
+ |---|---|---|
45
+ | 1 | Handback مسجّل في ملف المهمة | Task file |
46
+ | 2 | `Post-Execution Review` = PASS | `TeraPreExecutionGate.md` §6.2 |
47
+ | 3 | `Compliance Record` = COMPLIANT | Task file |
48
+ | 4 | `Owner Approval Required`: إن Yes → اعتماد صريح مسجّل | Owner Approval Gate |
49
+ | 5 | قرارات QA / Auditor / Security المطلوبة مسجّلة | §6.2 Independent Review |
50
+ | 6 | Cross-Record Consistency: لا تعارض بين Task/REGISTRY/PROJECT_STATE/DECISIONS/ACTIVITY/AUDIT_TRAIL | CORE §4.0.1 |
51
+
52
+ **أي شرط فاشل → لا إغلاق.** أبلغ بالسبب المحدد وانتظر قرار Majed.
53
+ > `/tera-approve` يسجّل **نية المالك**؛ ولا يتجاوز أبداً الشروط التقنية أعلاه.
54
+
55
+ ---
56
+
57
+ ## 4. Closure Transaction & Reconciliation (منع Partial/Split State)
58
+
59
+ الإغلاق = **معاملة واحدة قابلة للتحقق**، لا writes متفرقة:
60
+
61
+ ```text
62
+ 1. حدّد كل السجلات المستهدفة (Task file, TASK_REGISTRY, PROJECT_STATE,
63
+ PROJECT_ACTIVITY_LOG, DECISIONS_LOG, TERA_AUDIT_TRAIL, ISSUES_AND_GAPS عند الحاجة).
64
+ 2. احسب الحالة النهائية المطلوبة في كلٍّ منها.
65
+ 3. طبّقها كلها.
66
+ 4. أعد قراءتها وتأكد من التطابق (reconcile).
67
+ 5. إن تعذّر الإكمال → لا تُعلن Closed؛ أبلغ بحالة جزئية + ما تبقّى، واقترح الإصلاح.
68
+ ```
69
+
70
+ - أمر **`/tera-reconcile`** يفحص الاتساق ويصدر `CONSISTENT` أو `DRIFT_FOUND`.
71
+ - لا `Closed` مع أي سجل غير متزامن.
72
+
73
+ ---
74
+
75
+ ## 5. Command Conformance Gate
76
+
77
+ أي تغيير نظامي يمس: **phase ownership · task lifecycle · approval · path rules · state records · role boundaries**
78
+ → ضمن الـSCP، يجب فحص `.opencode/commands/*.md` المتأثرة وتحديثها في نفس الدفعة.
79
+ (يمتد هذا إلى فحص `scripts/validate-governance.mjs` حيث ينطبق.)
80
+
81
+ ---
82
+
83
+ ## 6. Path Semantics (توضيح)
84
+
85
+ - المسارات في الأوامر **مُحلّة** عبر §1 — لا تُقرأ حرفياً من الجذر.
86
+ - `project-control/…` في أي أمر = `<ProjectControlPath>/…` بعد الحل.