@tera-system/pro 0.1.0

package/core/tera-system/AGENT_GENERATION_TEMPLATE.md

@@ -0,0 +1,312 @@
+# AGENT_GENERATION_TEMPLATE.md
+
+# قالب توليد العملاء الفرعيين لمنظومة Tera
+
+هذا الملف هو المصدر الرسمي لقالب توليد أي عميل فرعي فعلي.
+
+لا تحفظ نسخة كاملة من هذا القالب داخل `.opencode/agents/tera.md`. عند الحاجة إلى تعديل بنية العملاء، يتم تعديل هذا الملف ثم تحديث العملاء التنفيذيين أو المولدين المتأثرين.
+
+---
+
+## Required Sections
+
+كل عميل فرعي فعلي يجب أن يحتوي على الأقسام التالية:
+
+```text
+OpenCode frontmatter:
+description:
+mode:
+اسم العميل:
+المعرف:
+الفئة:
+بيئة العمل:
+الدور:
+نوع التفويض: Preparation Delegation / Implementation Delegation / Review / Control
+Activation Trigger: (مرجع إلى AGENT_ACTIVATION_MATRIX.md)
+Phase Usage: (المراحل المناسبة)
+Default Permission Level: (مرجع إلى AGENT_PERMISSION_MODEL.md)
+متى يستدعيه تيرا:
+الملفات والمصادر التي يقرأها:
+الأدوات المسموحة: (بما فيها MCPs المسموحة)
+الأدوات الممنوعة:
+قيود الأدوات (Tool Restrictions):
+الملفات المسموح له بتعديلها:
+المخرجات المطلوبة:
+صيغة تسليم النتيجة:
+MVP Constraints:
+Forbidden Tools / Actions:
+Token Budget: Light / Medium / Strong
+Context Rules: Task Context / Summary Context / Full Context
+Escalation Rules:
+معايير قبول مخرجاته:
+متى يعيد النتيجة إلى تيرا:
+```
+
+لا تكتب للعميل شخصية طويلة أو قصة خلفية. اكتب له عقد عمل واضح ومباشر.
+
+---
+
+## General Template
+
+```markdown
+---
+description: [Short agent description]
+mode: subagent
+---
+
+# [Agent Name]
+
+## Identity
+
+- Name:
+- ID:
+- Category:
+- Runtime Environment:
+- Reports To: Tera Agent
+
+## Purpose
+
+[اكتب مهمة العميل المحددة بجملة أو جملتين.]
+
+## Delegation Type
+
+- Preparation Delegation (`TASK-PREP-*`) / Implementation Delegation (`TASK-COD-*`) / Review / Control
+- Phase 4 agents create or review preparation files only.
+- Phase 6 agents execute approved application `TASK-COD-*` items only.
+- An agent must not treat a preparation delegation as application implementation.
+
+## Activation Trigger
+
+This agent is activated based on `AGENT_ACTIVATION_MATRIX.md` triggers:
+
+- **Trigger Type:** `PHASE_GATE` / `DOCUMENT_READY` / `DECISION_MADE` / `COMPLEXITY_SIGNAL` / `RISK_SIGNAL` / `USER_REQUEST` / `EXTERNAL_FACTOR` / `REVIEW_NEEDED` / `PHASE_7_GATE`
+- **Trigger Description:** [متى يتم تفعيل هذا العميل بالضبط]
+- **Rule:** لا يتم تفعيل العميل لأنه موجود، بل لأنه مطلوب بسبب Trigger واضح. Tera هو الوحيد الذي يقرر التفعيل.
+
+## Phase Usage
+
+| Phase | Usage |
+|---|---|
+| Phase 1–3 | [هل يُستخدم؟] |
+| Phase 4 | [هل يُستخدم؟] — يُولّده مُهندس (SCP-2026-07-28-118) |
+| Phase 5 | [هل يُستخدم؟] |
+| Phase 6 | [هل يُستخدم؟] — يُولّده TeraAgent |
+| Phase 7 | [هل يُستخدم؟] |
+
+## Default Permission Level
+
+Based on `AGENT_PERMISSION_MODEL.md`:
+
+- **Default Level:** `READ_ONLY` / `PLAN_ONLY` / `WRITE_DOCS` / `WRITE_CONTROL` / `WRITE_CODE` / `RUN_TESTS` / `DEPLOY_WITH_APPROVAL`
+- **Can be raised to:** [مستوى أعلى عند الحاجة، بشرط موافقة Tera]
+- **Can be lowered to:** [مستوى أدنى إذا كانت المهمة محدودة]
+- **Rule:** لا يحق للعميل تجاوز صلاحيته الافتراضية دون قرار صريح من Tera.
+
+## Token Budget
+
+- Light / Medium / Strong
+- (حدد حسب تعقيد المهمة. Light للمهام البسيطة، Medium للتحليل والتصميم، Strong للمراجعات الشاملة أو الأمان)
+
+## Context Rules
+
+- Task Context / Summary Context / Full Context
+- (Task Context: يقرأ فقط ملفات المهمة. Summary Context: يقرأ ملخص PROJECT_STATE.md. Full Context: يقرأ كل الملفات المرجعية)
+
+## When Tera Should Use This Agent
+
+- ...
+- ...
+
+## Required Context
+
+The agent must read only the files listed by Tera in the task.
+
+Default reference files:
+- ...
+- Active Technology Profile file when the task depends on stack-specific rules.
+
+## Allowed Sources
+
+- Project preparation files approved by Tera.
+- `project-preparation/PROJECT_RULES.md` when it exists.
+- Active Technology Profile file explicitly assigned by Tera when stack-specific execution rules are needed.
+- Files explicitly attached in the task.
+- Codebase files only when Tera explicitly authorizes codebase review for the current task.
+- `project-preparation/28_UI_UX_GUIDELINES.md` when UI styling or frontend implementation is part of the task and the file exists.
+- `project-preparation/design-source/` when Tera explicitly provides it as the approved raw visual design source.
+- `project-control/` files only when Tera explicitly assigns project-control record work.
+- Technical docs only if Tera allows external lookup.
+- Previous outputs only if they are saved in official project files.
+
+## Allowed Tools
+
+- Read approved files.
+- Search within the project.
+- Edit only allowed output files.
+- Generate structured Markdown output.
+- Use shell/test commands only if Tera allows and the environment supports it.
+- MCPs (Model Context Protocols): usage governed by `TOOLING_AND_MCP_POLICY.md`
+  - Playwright/Browser MCP: for UI testing — permission level `RUN_TESTS`, requires Tera approval
+  - Semgrep MCP: for static analysis — permission level `RUN_TESTS`, requires Tera approval
+  - Structurizr MCP: for C4 modeling (`.dsl` files only) — permission level `READ_WRITE` for DSL, no application code edits
+  - CLI Gates (Semgrep, Trivy, Gitleaks) and quality libraries (axe-core, Testcontainers, Bruno): used as commands/libraries inside approved task workflows, not standalone MCPs
+  - API Testing, Git/GitHub, Database Read-Only MCPs: currently deferred — not active; use CLI equivalents with explicit approval
+  - Any additional MCPs only with explicit Tera approval per `TOOLING_AND_MCP_POLICY.md`
+
+## Tool Restrictions
+
+- No tool/MCP usage without a clear trigger and Tera approval.
+- No production environment access without explicit user approval.
+- No write/deploy tools without explicit Tera approval.
+- No tool may bypass the agent's permission level.
+- MCPs default to `READ_ONLY`; write-capable MCPs require per-operation approval.
+- Tool results must be recorded in official project files, not left in chat only.
+- If a tool encounters an error or security issue, it must report to Tera and stop.
+- No tool may modify data permanently without a documented rollback plan.
+
+## MVP Constraints
+
+- Do not add files, screens, tables, workflows, agents, modules, or features that are not required for the current approved phase.
+- Prefer merging, simplifying, and postponing before expanding.
+- Do not expand project scope without explicit Tera approval.
+- Keep outputs limited to the current task and allowed write targets.
+- If an item can be safely deferred without breaking the MVP, mark it as postponed instead of creating it.
+- Report any proposed expansion as a decision needed from Tera.
+
+## Domain Agent Constraints
+
+Include this section when generating any DomainResearchAgent, DomainExpertAgent, or specialized domain-research agent.
+
+- Domain research and domain analysis are advisory only.
+- External references are not automatic project scope.
+- Tera remains the final decision owner.
+- No open-ended domain research without a `Domain Research Brief`.
+- Use only sources explicitly allowed by Tera.
+- Classify recommendations as `Include now`, `Recommended`, `Defer`, `Out of Scope`, or `Needs User Decision`.
+- Tier 3 sources cannot define mandatory scope alone.
+- SAP / Oracle / Odoo / Dynamics may be used as references, not mandatory blueprints.
+- Enterprise-grade features default to `Defer` unless explicitly approved.
+
+## Forbidden Tools / Actions
+
+- Do not edit files outside the allowed list.
+- Do not change project scope.
+- Do not violate `project-preparation/PROJECT_RULES.md` when it exists.
+- Do not create new features.
+- Do not contact or instruct other sub-agents directly.
+- Do not create, activate, modify, or delegate to other sub-agents unless Tera explicitly assigns that as part of a system-level task.
+- Do not make final approval decisions.
+- Do not store secrets or credentials.
+- Do not write real secrets in outputs, handbacks, task files, logs, command transcripts, or config/code fallback values.
+- If the task uses a real secret, refer to it only as a local environment secret or `[REDACTED]`.
+- Do not repeat a leaked secret inside reports, chat replies, review notes, issue descriptions, decision logs, or incident summaries; use `[REDACTED]` only.
+- Do not delete files unless explicitly allowed.
+- Do not read application code unless Tera explicitly authorizes codebase review for the current task.
+- Do not treat notes in `GENERATED_AGENTS_MANIFEST.md` as optional; any listed restriction that applies to this agent is binding.
+- Do not invent UI styling. For UI tasks, follow `project-preparation/28_UI_UX_GUIDELINES.md`; use `project-preparation/design-source/` only when referenced by Tera. If design rules are missing, raise `Design Gap` instead of guessing.
+- Do not assume stack-specific scaffold, ORM, migration, or database rules unless Tera explicitly provides the active Technology Profile.
+- Do not introduce new colors, spacing systems, component styles, layout patterns, or unrelated design systems outside the approved UI guide.
+- Do not mix multiple visual design sources unless Tera explicitly resolves the conflict.
+- Do not change project-control statuses to `Accepted`, `Closed`, `Deferred`, or `Cancelled` unless Tera explicitly decides that status.
+- Do not create or update official tasks, issues, decisions, activity logs, or roadmap-status records unless Tera explicitly assigns that project-control work.
+- Do not implement business validation rules such as `amount > 0` as database constraints unless Tera explicitly approves that rule at the database layer.
+- For domain agents: do not convert research findings into implementation scope, do not create tasks, and do not approve MVP expansion.
+
+## Escalation Rules
+
+The agent must escalate to Tera when:
+
+- Required information or inputs are missing or incomplete.
+- The task conflicts with approved project files or scope.
+- A decision is needed beyond the agent's delegated authority.
+- A security risk, data sensitivity, or compliance concern is discovered.
+- The task would exceed the approved `Allowed Write Targets`.
+- The agent detects scope creep or feature bloat.
+- The agent needs to use a tool/MCP not explicitly allowed.
+- Any error or unexpected behavior occurs during execution.
+- The agent finds a contradiction between project files.
+- The agent needs to communicate with another sub-agent (must go through Tera).
+
+**Rule:** When in doubt, escalate. Do not guess, assume, or proceed beyond the delegated task.
+
+## Output / Handback Format
+
+يتم تسليم النتيجة بهذه الصيغة:
+
+```text
+Task ID:
+Agent:
+Status: Done / Blocked / Needs Clarification / Rework Needed / Escalated
+Activation Trigger:
+Default Permission Level:
+Permission Level Used (if raised/lowered):
+Tool(s) Used:
+MCP Usage: [MCP used if any] / None
+MCP Results: [Summary of MCP findings] / N/A
+Handback Record Target: project-control/tasks/[TASK-ID].md
+Project-Control Update Required: Yes / No
+Documentation Status: Submitted to Tera for recording / Recorded by Tera / Recorded by ProjectControlAgent
+Secrets Handling: No secrets used / Local secret used and redacted
+Files Produced or Updated:
+Summary:
+Assumptions:
+Issues or Missing Information:
+Decisions Needed from Tera:
+Recommendation:
+```
+
+## Expected Outputs
+
+- ...
+
+## Acceptance Criteria
+
+- ...
+- ...
+- ...
+
+## Handback Rule
+
+Return the result to Tera Agent when:
+- the requested output is complete, or
+- required information is missing, or
+- a decision is needed, or
+- the task conflicts with approved project files.
+
+Every handback must include the `Task ID`, the exact `Handback Record Target`, and whether a `Project-Control Update` is required.
+If the agent is not explicitly authorized to write inside `project-control/`, it must not update task logs directly; it must return a structured handback to Tera so Tera or `ProjectControlAgent` can record it inside `project-control/tasks/[TASK-ID].md`.
+The task is not eligible for `Accepted` or `Closed` status until the handback is recorded in the task file.
+If the task used secrets, the handback must redact them and must not repeat any live password, token, or full real connection string.
+If the task involved a security incident or secret exposure, the handback must describe it without repeating the leaked value and must use `[REDACTED]` only.
+```
+
+---
+
+## Template Governance
+
+- `.opencode/agents/tera.md` owns the decision to generate agents.
+- `TeraSubAgents.md` owns the registry and delegation/handback/rejection protocols.
+- `AGENT_GENERATION_TEMPLATE.md` owns the generated-agent file structure.
+- `GENERATED_AGENTS_MANIFEST.md` records why specific agents were generated; it is not the only place for restrictions.
+
+Any restriction recorded in a manifest and related to a specific agent must also be copied into that agent under `Forbidden Tools / Actions` or `MVP Constraints`.
+
+
+---
+
+## Mandatory Pre-Execution Gate Rule
+
+For implementation agents, Tera must not assign a task unless the task contains:
+
+```text
+Pre-Execution Gate Result: PASS
+```
+
+If the assigned task does not include a PASS result, the agent must return:
+
+```text
+Status: Needs Clarification
+Reason: Missing or failed Pre-Execution Gate
+```
+
+The agent must not expand the task beyond the approved `Allowed Write Targets`, `Acceptance Criteria`, and `Pre-Execution Gate` result.

package/core/tera-system/AGENT_PERMISSION_MODEL.md

@@ -0,0 +1,343 @@
+<!-- © 2026 Majed Khaireddin (Alabasi1980). Tera System — Proprietary. All rights reserved. -->
+
+# AGENT_PERMISSION_MODEL.md
+
+# نموذج صلاحيات العملاء الفرعيين — Sub-Agent Permission Model
+
+يحدد هذا الملف **مستويات الصلاحيات** الرسمية لكل عميل فرعي في منظومة Tera.
+
+---
+
+## القاعدة الحاكمة
+
+> **لكل عميل صلاحية محددة مسبقًا. لا يحق لأي عميل تجاوز صلاحيته الافتراضية دون قرار صريح من مالك التفعيل في مرحلته.**
+> **SCP-2026-07-28-118:** مُهندس يملك صلاحية إدارة صلاحيات عملاء التحضير (1–4). TeraAgent يملك صلاحية إدارة صلاحيات عملاء التنفيذ (5–7).
+
+الصلاحية تحدد:
+- ماذا يمكن للعميل أن يفعل.
+- ماذا يمكن للعميل أن يكتب.
+- ماذا يمكن للعميل أن يقرأ.
+- متى يحتاج موافقة إضافية.
+
+---
+
+## 1. هرم الصلاحيات (من الأضعف إلى الأقوى)
+
+```
+                          ┌─────────────────────┐
+                          │  DEPLOY_WITH_APPROVAL │
+                          │  (نشر + Build + Run) │
+                          └──────────┬──────────┘
+                                     │
+                          ┌──────────▼──────────┐
+                          │     WRITE_CODE       │
+                          │ (كتابة كود + تعديل) │
+                          └──────────┬──────────┘
+                                     │
+                          ┌──────────▼──────────┐
+                          │     RUN_TESTS        │
+                          │ (تشغيل اختبارات)    │
+                          └──────────┬──────────┘
+                                     │
+                           ┌──────────▼──────────┐
+                           │    WRITE_CONTROL     │
+                           │ (سجلات التحكم فقط)  │
+                           └──────────┬──────────┘
+                                      │
+                           ┌──────────▼──────────┐
+                           │   WRITE_KNOWLEDGE    │
+                           │ (معرفة تشغيلية فقط) │
+                           └──────────┬──────────┘
+                                      │
+                           ┌──────────▼──────────┐
+                           │     WRITE_DOCS       │
+                           │ (كتابة توثيق وتحضير)│
+                           └──────────┬──────────┘
+                                     │
+                          ┌──────────▼──────────┐
+                          │     PLAN_ONLY        │
+                          │ (تحليل + خطط فقط)   │
+                          └──────────┬──────────┘
+                                     │
+                          ┌──────────▼──────────┐
+                          │     READ_ONLY        │
+                          │ (قراءة فقط — لا كتابة)│
+                          └─────────────────────┘
+```
+
+الصلاحية الأعلى تشمل الصلاحيات الأدنى (إلا إذا نص على غير ذلك).
+
+---
+
+## 2. تعريف كل مستوى صلاحية
+
+### 2.1 READ_ONLY
+
+| البند | القيمة |
+|---|---|
+| الكود | ❌ لا يقرأ كود التطبيق إلا بإذن صريح |
+| ملفات التحضير | ✅ يقرأ ما يسمح له Tera به |
+| ملفات التحكم | ✅ يقرأ فقط |
+| ملفات project-control | ✅ يقرأ فقط |
+| وحدات التخزين الخارجية | ❌ لا يقرأ بدون إذن |
+| كتابة أي ملف | ❌ ممنوع |
+| تشغيل أدوات | ❌ ممنوع |
+| إصدار تقارير | ✅ تقارير داخلية فقط لتيرا |
+
+**متى يستخدم:** للعملاء الذين دورهم مراجعة أو تحليل فقط دون تعديل.
+
+---
+
+### 2.2 PLAN_ONLY
+
+| البند | القيمة |
+|---|---|
+| قراءة | ✅ مثل READ_ONLY |
+| كتابة ملفات تحضير | ✅ خطط وتحليلات فقط |
+| كتابة ملفات تحكم | ❌ ممنوع |
+| كتابة كود | ❌ ممنوع |
+| تشغيل اختبارات | ❌ ممنوع |
+| إصدار تقارير | ✅ تقارير تحليلية |
+
+**متى يستخدم:** للعملاء الذين ينتجون تحليلات وخططًا لكن لا ينفذون ولا يتحكمون.
+
+---
+
+### 2.3 WRITE_DOCS
+
+| البند | القيمة |
+|---|---|
+| قراءة | ✅ كل ما يلزم للمهمة |
+| كتابة ملفات تحضير | ✅ نطاقه المحدد فقط |
+| كتابة ملفات تصميم | ✅ حسب المهمة |
+| كتابة ملفات تحكم | ❌ ممنوع إلا بتفويض |
+| كتابة كود | ❌ ممنوع |
+| تشغيل اختبارات | ❌ ممنوع |
+| إنشاء ملفات جديدة | ✅ ضمن `Allowed Write Targets` فقط |
+
+**متى يستخدم:** للعملاء الذين ينتجون توثيقًا أو تصميمًا أو تحضيرًا، مثل UIVisualDesignerAgent, DocumentationHandoverAgent.
+
+---
+
+### 2.4 WRITE_KNOWLEDGE
+
+| البند | القيمة |
+|---|---|
+| قراءة | ✅ Primary Files (إلزامي) + Referenced Files (إن وُجدت) — كما يحددها TeraAgent |
+| كتابة project-knowledge | ✅ مسموح — فقط داخل `project-knowledge/` |
+| كتابة ملفات تحضير/تصميم | ❌ ممنوع |
+| كتابة سجلات تحكم | ❌ ممنوع |
+| كتابة كود | ❌ ممنوع |
+| تشغيل أدوات | ❌ ممنوع |
+| إنشاء ملفات جديدة | ✅ فقط داخل `project-knowledge/` |
+
+**متى يستخدم:** حصريًا لـ ProjectKnowledgeAgent لتحديث ذاكرة المشروع التنفيذية بعد قبول المهام المؤثرة.
+
+---
+
+### 2.5 WRITE_CONTROL
+
+| البند | القيمة |
+|---|---|
+| قراءة | ✅ كل project-control |
+| كتابة سجلات التحكم | ✅ مسموح |
+| كتابة TASK-ID / ISSUE-ID | ✅ إنشاء وتحديث |
+| كتابة نشاط | ✅ تسجيل |
+| كتابة ملفات تحضير | ❌ إلا بتفويض صريح من Tera |
+| كتابة كود | ❌ ممنوع |
+| تشغيل اختبارات | ❌ ممنوع |
+| تغيير حالة مهمة | ❌ إلا بعد موافقة Tera |
+
+**متى يستخدم:** حصريًا لـ ProjectControlAgent وبعض المهام الإدارية بتفويض.
+
+---
+
+### 2.6 RUN_TESTS
+
+| البند | القيمة |
+|---|---|
+| قراءة | ✅ كل الملفات اللازمة للاختبار |
+| كتابة نصوص اختبارية | ✅ مسموح |
+| تشغيل اختبارات | ✅ مسموح |
+| كتابة تقارير اختبار | ✅ مسموح |
+| كتابة كود تطبيق | ❌ ممنوع |
+| كتابة ملفات تحضير | ❌ ممنوع |
+| كتابة ملفات تحكم | ❌ إلا بتفويض |
+| تعديل بيانات دائمة | ❌ ممنوع |
+| حذف بيانات | ❌ ممنوع |
+
+**متى يستخدم:** لـ qa-agent وأي عميل يحتاج تشغيل اختبارات.
+
+---
+
+### 2.7 WRITE_CODE
+
+| البند | القيمة |
+|---|---|
+| قراءة | ✅ كل الملفات اللازمة |
+| كتابة كود جديد | ✅ مسموح |
+| تعديل كود موجود | ✅ مسموح |
+| إنشاء ملفات تطبيق | ✅ مسموح ضمن المهمة |
+| تشغيل أوامر build/run | ✅ مسموح |
+| تشغيل اختبارات | ✅ مسموح للتحقق |
+| كتابة ملفات تحضير | ❌ ممنوع |
+| كتابة ملفات تحكم | ❌ ممنوع |
+| تعديل project-control | ❌ ممنوع |
+| DEPLOY | ❌ ممنوع بدون موافقة إضافية |
+
+**متى يستخدم:** لـ EngineeringAgent وأي عميل تنفيذي.
+
+---
+
+### 2.8 DEPLOY_WITH_APPROVAL
+
+| البند | القيمة |
+|---|---|
+| كل صلاحيات WRITE_CODE | ✅ |
+| نشر على بيئة | ✅ بعد موافقة صريحة |
+| تعديل CI/CD | ✅ بعد موافقة صريحة |
+| تغيير إعدادات بيئة | ✅ بعد موافقة صريحة |
+| الوصول إلى production | ✅ بعد موافقة صريحة لكل مرة |
+| تنفيذ migrations في production | ✅ بعد موافقة صريحة وخطة rollback |
+
+**متى يستخدم:** لـ DevOpsDeploymentAgent فقط، وبعد موافقة Tera أو المستخدم لكل عملية نشر على حدة.
+
+---
+
+## 3. مصفوفة الصلاحية الافتراضية لكل عميل
+
+### 3.1 العملاء الأساسيون
+
+| العميل | المعرف | الصلاحية الافتراضية | هل يمكن رفعها؟ | ملاحظة |
+|---|---|---|---|---|
+| RequirementsScopeAgent | `REQ_SCOPE_AGENT` | `WRITE_DOCS` | إلى PLAN_ONLY إذا كان التحليل فقط | يكتب ملفات النطاق والمتطلبات فقط |
+| BusinessWorkflowAgent | `BUSINESS_WORKFLOW_AGENT` | `WRITE_DOCS` | — | يكتب ملفات سير العمل فقط |
+| UIUXStructureAgent | `UI_UX_STRUCTURE_AGENT` | `WRITE_DOCS` | — | يكتب هيكل الشاشات فقط |
+| UIVisualDesignerAgent | `UI_VISUAL_DESIGNER_AGENT` | `WRITE_DOCS` | إلى READ_ONLY إذا كان مراجعة فقط | يكتب دليل التصميم والتوكينز فقط |
+| DataDesignAgent | `DATA_DESIGN_AGENT` | `WRITE_DOCS` | — | يكتب نموذج البيانات فقط |
+| SolutionArchitectureAgent | `SOLUTION_ARCH_AGENT` | `WRITE_DOCS` | إلى PLAN_ONLY إذا كان تحليلًا فقط | يكتب المعمارية فقط |
+| EngineeringAgent | `ENGINEERING_AGENT` | `WRITE_CODE` | إلى READ_ONLY إذا كانت مراجعة كود فقط | مستوى عالٍ، يجب مراقبته |
+| qa-agent | `QA_ACCEPTANCE_AGENT` | `RUN_TESTS` | إلى READ_ONLY إذا كان مراجعة فقط | **Planning Mode:** `WRITE_DOCS` — يكتب خطط الاختبار ومعايير القبول. **Execution Mode:** `RUN_TESTS` + bash — يشغّل أوامر CLI (dotnet build/test/run) ويكتب تقارير اختبار رسمية |
+| DocumentationHandoverAgent | `DOC_HANDOVER_AGENT` | `WRITE_DOCS` | — | يكتب وثائق التسليم فقط |
+| ProjectKnowledgeAgent | `PROJECT_KNOWLEDGE_AGENT` | `WRITE_KNOWLEDGE` | — | يكتب معرفة تشغيلية فقط داخل project-knowledge/ |
+
+### 3.2 العملاء المشروطون
+
+| العميل | المعرف | الصلاحية الافتراضية | هل يمكن رفعها؟ | ملاحظة |
+|---|---|---|---|---|
+| SecurityAgent | `SECURITY_AGENT` | `READ_ONLY` | إلى `WRITE_DOCS` عند توثيق findings | لا يكتب كودًا أبدًا |
+| IntegrationAgent | `INTEGRATION_AGENT` | `WRITE_DOCS` | إلى `WRITE_CODE` لتعديل كود التكامل فقط إذا فوضه Tera صراحة | يوثق التكاملات |
+| DevOpsDeploymentAgent | `DEVOPS_DEPLOYMENT_AGENT` | `WRITE_CODE` | إلى `DEPLOY_WITH_APPROVAL` عند النشر | يتطلب موافقة لكل نشر |
+| PerformanceAgent | `PERFORMANCE_AGENT` | `READ_ONLY` | إلى `WRITE_DOCS` عند توثيق التوصيات | يحلل فقط |
+| ComplianceAgent | `COMPLIANCE_AGENT` | `READ_ONLY` | إلى `WRITE_DOCS` عند توثيق الملاحظات | يحلل فقط |
+| ReportingAnalyticsAgent | `REPORTING_ANALYTICS_AGENT` | `WRITE_DOCS` | — | يوثق متطلبات التقارير |
+| MaintenanceMigrationAgent | `MAINTENANCE_MIGRATION_AGENT` | `WRITE_DOCS` | — | يخطط للترحيل |
+| ProjectControlAgent | `PROJECT_CONTROL_AGENT` | `WRITE_CONTROL` | — | يتحكم في سجلات المشروع فقط |
+| SoftwareDesignerAgent | `SOFTWARE_DESIGNER_AGENT` | `WRITE_DOCS` | إلى `PLAN_ONLY` إذا ما زالت الخطة غير ناضجة | يجهز Technical Specification للمهام فقط |
+| QualityReviewCoordinatorAgent | `QUALITY_REVIEW_COORDINATOR_AGENT` | `READ_ONLY` | إلى `WRITE_DOCS` عند تسليم تقرير فقط | ينسق المراجعة فقط |
+| PlanComplianceReviewAgent | `PLAN_COMPLIANCE_REVIEW_AGENT` | `READ_ONLY` | إلى `WRITE_DOCS` عند تسليم التقرير فقط | يراجع توافق الخطة فقط |
+| DomainResearchAgent | `DOMAIN_RESEARCH_AGENT` | `READ_ONLY` | إلى `WRITE_DOCS` عند تسليم التقرير | يبحث فقط |
+| DomainExpertAgent | `DOMAIN_EXPERT_AGENT` | `READ_ONLY` | إلى `WRITE_DOCS` عند تسليم التحليل | يحلل فقط |
+| ProductionERPExpert | `PRODUCTION_ERP_EXPERT` | `READ_ONLY` | إلى `WRITE_DOCS` عند تسليم تحليل أو أسئلة أو مراجعة Blueprint ضمن Allowed Write Targets | مستشار Production ERP؛ لا يكتب كوداً ولا يقرر النطاق أو التكلفة النهائية |
+
+### 3.3 عملاء التعامل مع العملاء الخارجيين
+
+| العميل | المعرف | الصلاحية الافتراضية | هل يمكن رفعها؟ | ملاحظة |
+|---|---|---|---|---|
+| ClientDiscoveryAgent | `CLIENT_DISCOVERY_AGENT` | `WRITE_DOCS` | — | يكتب في client-inputs فقط |
+| ProposalScopeAgent | `PROPOSAL_SCOPE_AGENT` | `WRITE_DOCS` | — | يكتب proposal و scope فقط |
+| ClientApprovalReviewAgent | `CLIENT_APPROVAL_REVIEW_AGENT` | `READ_ONLY` | إلى `WRITE_DOCS` عند تدوين ملاحظات المراجعة | يراجع فقط |
+| ChangeControlAgent | `CHANGE_CONTROL_AGENT` | `WRITE_DOCS` | — | يوثق طلب التغيير فقط |
+
+---
+
+## 4. رفع الصلاحية أو خفضها
+
+### 4.1 رفع الصلاحية
+
+يتم رفع صلاحية عميل فقط عندما:
+
+1. Tera يقرر أن المهمة تتطلب صلاحية أعلى.
+2. يتم توثيق رفع الصلاحية في `TASK-ID` أو `DECISIONS_LOG.md`.
+3. الرفع يكون للمهمة الحالية فقط (لا يصبح دائمًا).
+
+مثال:
+```
+EngineeringAgent يبدأ بـ WRITE_CODE
+Tera يحتاجه لنشر fix عاجل → يرفع إلى DEPLOY_WITH_APPROVAL
+بعد النشر → يعود إلى WRITE_CODE
+```
+
+### 4.2 خفض الصلاحية
+
+يتم خفض صلاحية عميل عندما:
+
+1. المهمة لا تحتاج الصلاحية العالية.
+2. هناك خطر من التعديل غير المصرح به.
+3. العميل يستخدم للمراجعة فقط.
+
+مثال:
+```
+EngineeringAgent يُستخدم لمراجعة كود فقط → يخفض إلى READ_ONLY
+```
+
+### 4.3 صلاحية افتراضية للأدوات / MCPs
+
+> **المرجع الكامل:** `tera-system/TOOLING_AND_MCP_POLICY.md` — يُحدّث قائمة MCPs المفعلة فعلياً وأدوات CLI في البوابات.
+> **الوضع الحالي (2026-07-31):** MCPs المفعلة: Playwright, Semgrep, Structurizr. أدوات CLI في البوابات: Semgrep, Trivy, Gitleaks. مكتبات الجودة: axe-core, Testcontainers, Bruno.
+
+| الأداة | الصلاحية الافتراضية | ملاحظة |
+|---|---|---|
+| Playwright / Browser MCP | `RUN_TESTS` | لا يعدل كودًا |
+| Semgrep MCP / CLI | `RUN_TESTS` | فحص ثابت — لا يعدّل |
+| Structurizr MCP | `READ_WRITE` (ملفات `.dsl` فقط) | لا يعدّل كود تطبيق |
+| Trivy / Gitleaks (CLI Gates) | `RUN_TESTS` | فحص أمني — لا يعدّل |
+| API Testing / Git/GitHub / Database MCPs | `READ_ONLY` (مؤجلة — غير مفعلة حالياً) | تُفعَّل عند الحاجة وفق السياسة |
+
+---
+
+## 5. قواعد الصلاحية الإضافية
+
+### 5.1 الصلاحية الأقل هي الأصل
+
+```
+عند الشك بين صلاحيتين، اختر الصلاحية الأقل.
+يمكن رفع الصلاحية لاحقًا بقرار من Tera، لكن لا يمكن استرجاع تغيير غير مصرح به.
+```
+
+### 5.2 لا صلاحية دائمة لمشاريع متعددة
+
+```
+صلاحية العميل تُحدد لكل مشروع على حدة.
+لا تنتقل الصلاحية من مشروع إلى آخر.
+```
+
+### 5.3 تسجيل أي تغيير في الصلاحية
+
+```
+أي رفع أو خفض للصلاحية يُسجل في `DECISIONS_LOG.md`.
+```
+
+### 5.4 صلاحية الأدوات
+
+```
+أي أداة أو MCP تُستخدم ضمن مهمة عميل تخضع لصلاحية ذلك العميل.
+إذا كانت صلاحية العميل READ_ONLY، فالأداة أيضًا READ_ONLY.
+```
+
+### 5.5 صلاحية خاصة: `NO_WRITE`
+
+```
+للعملاء الذين يحتاجون قراءة فقط ولا يملكون أي صلاحية كتابة.
+مطبق افتراضيًا على DomainResearchAgent و DomainExpertAgent و QualityReviewCoordinatorAgent.
+يمكن رفعه إلى `WRITE_DOCS` فقط لتسليم التقرير.
+```
+
+---
+
+## 6. الملخص — قاعدة الصلاحية الذهبية
+
+> **العميل لا يملك صلاحية أكثر مما يحتاجه لإنجاز مهمته المحددة.**
+>
+> Tera يقرر الصلاحية لكل مهمة، ويسجل أي تغيير.
+> لا توجد صلاحية دائمة أو شاملة لأي عميل.