@nomos-arc/arc 0.1.0

package/docs/integrity-gate/overview.md

@@ -0,0 +1,108 @@
+تركيزنا الآن سينصب على تحويل **nomos-arc.ai** من مجرد أداة تحليلية إلى **محرك حوكمة (Governance Engine)**. الهدف هو بناء صمام أمان يمنع التدهور المعماري (Architectural Decay) آلياً.
+
+إليك التصميم الهندسي لـ **CI/CD Integrity Gate**:
+
+---
+
+## 1. بنية المقارنة (State Differential Analysis)
+لتحقيق الحوكمة، يجب أن ننتقل من "قراءة الخريطة" إلى "مقارنة الحالات". العملية تعتمد على مقارنة مخرجات `arc map` بين فرع الـ (Base) وفرع الـ (Feature).
+
+### خوارزمية كشف الانحراف (Drift Detection Algorithm)
+نعرّف "معامل التأثير المعماري" ($I$) للتعديل المقترح كدالة في عمق العقدة وعدد التبعيات المتأثرة:
+
+$$I(\Delta) = \sum_{i \in \text{Modified}} (\omega_{d} \cdot \frac{1}{\text{depth}_i} + \omega_{c} \cdot \text{dependents}_i)$$
+
+حيث:
+* $\omega_{d}$: وزن العمق (كلما قل العمق، زادت الخطورة).
+* $\omega_{c}$: وزن الاتصال (Connectivity).
+
+إذا تجاوزت قيمة $I$ حداً معيناً (Threshold) دون وجود "شهادة مراجعة" (`arc review`) موقعة إلكترونياً، يتم كسر الـ Pipeline.
+
+---
+
+## 2. تسلسل العمل في GitHub Action (The Pipeline Sequence)
+
+يعمل الـ Runner وفق التسلسل التالي لضمان النزاهة:
+
+1.  **Environment Setup:** تثبيت Node.js وتهيئة مفتاح `GEMINI_API_KEY` (لعمليات الـ Enrichment إذا لزم الأمر).
+2.  **Base Map Recovery:** محاولة استعادة `project_map.json` الخاص بفرع الـ Main من الـ Cache أو إعادة توليده.
+3.  **Head Map Generation:** تشغيل `arc map` على كود الـ PR الحالي لتوليد الخريطة الجديدة.
+4.  **Semantic Diffing:** تشغيل أمر جديد مقترح وهو `arc compare --base base_map.json --head head_map.json`.
+5.  **Policy Evaluation:** التحقق من القواعد (Rules) المحددة في `.nomos-config.json`.
+
+
+
+---
+
+## 3. منطق الحارس (The Gatekeeper Logic)
+
+يجب أن يركز الـ `arc compare` على ثلاثة أنواع من الانتهاكات:
+
+| نوع الانتهاك | الوصف التقني | الإجراء في CI |
+| :--- | :--- | :--- |
+| **Circular Dependency** | اكتشاف حلقة تبعية جديدة (عن طريق Tarjan's SCC). | **Block (Exit 1)** |
+| **Core Module Bloat** | زيادة الـ `dependents_count` لموديول أساسي بنسبة > 20%. | **Warning/Block** |
+| **Semantic Drift** | تغيير الـ `purpose` في مخرجات الـ AI دون تحديث الـ Documentation. | **Warning** |
+| **Integrity Breach** | وجود كود معدل لا يمتلك `sha256` مطابق في الـ `CertificatePayload`. | **Block (Critical)** |
+
+---
+
+## 4. نموذج الـ GitHub Action Workflow (`.github/workflows/nomos-gate.yml`)
+
+```yaml
+name: nomos-arc Architectural Gate
+
+on:
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  governance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # مهم للحصول على تاريخ الفروع للمقارنة
+
+      - name: Install nomos-arc.ai
+        run: npm install -g .
+
+      - name: Generate Current Map
+        run: arc map
+        env:
+          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+
+      - name: Run Integrity Check
+        id: nomos_check
+        run: |
+          # استدعاء أداة المقارنة
+          # ستقوم الأداة بمقارنة الخريطة الحالية بخريطة الفرع الرئيسي
+          arc compare --fail-on-drift --threshold 0.8
+        
+      - name: Comment on PR
+        if: failure()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: '⚠️ **nomos-arc.ai Governance Alert:** Architectural drift detected. High-impact core modules modified without proper semantic alignment. Please run `arc review` locally.'
+            })
+```
+
+---
+
+## 5. ميزة "العقد الدلالي" (Semantic Contract Enforcement)
+
+لإتمام هذا الربط، نحتاج لتعديل في الـ `arc-cli` يدعم:
+* **Checkpointing:** القدرة على حفظ "بصمة" معمارية للمشروع عند كل Release مستقر.
+* **Shadow Comparison:** مقارنة الـ AST المولد من الـ PR مقابل الـ AST المخزن في الخريطة الأصلية دون الحاجة لملفات الـ `.ts` الأصلية (لزيادة الخصوصية والسرعة).
+
+**بهذا نضمن:**
+1. لا يتم دمج أي كود يكسر الـ Graph.
+2. لا يتم تغيير الـ Core Logic إلا بعلم الـ Reviewer Agent.
+3. التوثيق (Semantic Info) يظل دائماً متزامناً مع الكود الفعلي.
+
+هل نبدأ بصياغة خوارزمية الـ `compare` داخل الـ `src/core/` لتمكين الـ CLI من اكتشاف هذه الفروقات؟

package/docs/management/manger-task.md

@@ -0,0 +1,99 @@
+تصميم ذكي وفعّال. فصل "واجهة المستخدم" (ملفات Markdown للعميل) عن "النظام العصبي" (ملفات YAML للـ AI) يحقق مبدأ **Separation of Concerns** ويسمح بتحسين الـ Tokens في الـ Prompts، حيث تتعامل الوكلاء مع بيانات مهيكلة مباشرة.
+
+سأقوم بصياغة الهيكل المقترح لهذا النظام مع تعريف بروتوكول التشغيل لكل مرحلة.
+
+---
+
+## أولاً: الهيكل التنظيمي للمجلدات (Dual-Storage Architecture)
+
+سيتم تقسيم البيانات إلى مستويين:
+1.  **المستوى الظاهري (Human-Readable):** تحت مسمى `tasks-management/` بصيغة `.md`.
+2.  **المستوى العميق (Machine-Readable):** تحت مسمى `.nomos/` بصيغة `.yaml`.
+
+```text
+project-root/
+├── tasks-management/               # للمطور والعميل (Human-Facing)
+│   ├── tasks/                      # [ID]-task-description.md
+│   ├── plans/                      # [ID]-implementation-plan.md
+│   ├── reports/                    # [ID]-red-team-critique.md
+│   └── certificates/               # [ID]-completion-certificate.md
+│
+└── .nomos/                         # لمحرك الذكاء الاصطناعي (Agent-Facing)
+    ├── state/                      # [ID]-lifecycle.yaml (الحالة اللحظية)
+    ├── context/                    # [ID]-raw-plan.yaml (بيانات تقنية مكثفة)
+    ├── rules/                      # architecture-constraints.yaml
+    └── graph/                      # project_map.json & vector_index/
+```
+
+---
+
+## ثانياً: دورة حياة المهمة (State Machine Sequence)
+
+سنستخدم ملف الـ `.yaml` داخل `.nomos/state/` كمصدر وحيد للحقيقة (Source of Truth) لنظام الحالة.
+
+### 1. مرحلة التهيئة (`arc init <task>`)
+* **Action:** إنشاء ملف `task.md` (بسيط للعميل) وملف `lifecycle.yaml` (يحتوي على الـ Meta-data والـ SHA-256 للبداية).
+* **State:** `status: DRAFT`.
+
+### 2. مرحلة التخطيط (`arc plan <task>`)
+* **Action:** يقوم الـ Planner Agent بقراءة الـ `project_map.json` والقواعد، ثم يولد الخطة.
+* **Output:** * `plans/[ID]-plan.md` (شرح منطقي).
+    * `.nomos/context/[ID]-plan.yaml` (قائمة بالتعديلات البرمجية الدقيقة، الـ Endpoints، وتغييرات الـ Schema).
+* **State:** `status: PLANNING_COMPLETED`.
+
+### 3. مرحلة الطعن (The Red Team / Adversarial Review)
+هنا تبدأ الـ Loop الحقيقية لمنع الهلوسة.
+* **Action:** يقوم الـ Red Team Agent بتحليل الـ `.yaml` الخاص بالخطة مقابل القواعد المعمارية.
+* **Output:** * `reports/[ID]-critique.md` (تنبيهات للمستخدم).
+    * `.nomos/state/[ID]-critique.yaml` (قائمة بالثغرات المكتشفة بـ `severity: high/medium`).
+* **Loop:** إذا وجدت ثغرات `high` يتم إعادة المهمة لحالة `PLANNING` آلياً مع حقن التقرير في البرومبت.
+
+### 4. مرحلة التنفيذ والتوثيق (`arc apply`)
+* **Action:** بعد الموافقة، يتم تنفيذ الكود في Shadow Branch.
+* **Certificate:** توليد شهادة تشفيرية تربط بين:
+    * `Initial Task Hash`
+    * `Approved Plan Hash`
+    * `Final Code Diff Hash`
+* **State:** `status: CERTIFIED`.
+
+
+
+---
+
+## ثالثاً: هيكل ملف الحالة الـ YAML (المحرك)
+
+هذا النموذج لما سيقرأه الـ Agent في كل خطوة لضمان عدم التشتت:
+
+```yaml
+# .nomos/state/TASK-001.yaml
+task_id: TASK-001
+version: 1.2
+metadata:
+  created_at: 2026-04-10T21:00:00Z
+  branch: nomos/feat-auth-fix
+  current_step: RED_TEAM_REVIEW
+
+integrity_chain:
+  task_hash: sha256:e3b0c442...
+  current_plan_hash: sha256:7f83b169...
+
+convergence_metrics:
+  iterations: 2
+  red_team_score: 0.85 # يحتاج 0.90 للعبور
+  unresolved_issues: 1
+
+shadow_state:
+  affected_files:
+    - src/core/auth.ts
+    - src/api/middleware.ts
+  dependency_impact: low
+```
+
+---
+
+## رابعاً: الأكشن القادم (Implementation Step)
+
+للبدء في تنفيذ هذه "الدورة الثالثة" برمجياً، نحتاج لبناء الـ **Orchestrator Class**. هذا الكلاس سيكون مسؤولاً عن:
+1.  **File Mirroring:** عندما يكتب الـ Agent ملف YAML، يقوم الكلاس تلقائياً بتوليد الـ Markdown المقابل له للعميل.
+2.  **Git Automation:** التعامل مع الـ Shadow Branches والتأكد من أن الـ `commit message` تحتوي على الـ `Task-ID`.
+

package/docs/management/scafffold.md

@@ -0,0 +1,76 @@
+To ensure the **nomos-arc.ai** environment is governed by deterministic logic rather than heuristic guesswork, the `thresholds` section in `.nomos-config.json` acts as the "Decision Logic" layer. These parameters define the boundary between acceptable architectural evolution and risky hallucination.
+
+Here is the detailed analytical breakdown of the recommended thresholds:
+
+---
+
+## 1. Semantic Similarity Threshold (`default_threshold`)
+
+This threshold determines the sensitivity of the `arc search` engine. Since nomos-arc.ai uses $L2$-normalized unit vectors, the similarity score $s$ is derived from the dot-product distance $d_{\text{dot}}$.
+
+* **Recommended Value:** `0.70`
+* **Engineering Rationale:** * **$s > 0.85$:** Extremely high precision. Only returns near-identical conceptual matches. May miss relevant context that uses different terminology.
+    * **$s < 0.60$:** High noise. Returns vaguely related files, increasing "Token Bloat" and distracting the AI Planner.
+    * **The "Goldilocks" Zone ($0.70$):** Balances recall (finding related logic) and precision (filtering out irrelevant noise).
+
+---
+
+## 2. Convergence Score (`convergence_threshold`)
+
+This is the most critical metric for the **Cybernetic Loop**. It defines the minimum score required from the **Red Team (Adversary)** before a plan is allowed to proceed to the `apply` (execution) phase.
+
+* **Recommended Value:** `0.90`
+* **Mathematical Representation:**
+    $$S = \frac{I_{resolved}}{I_{total}} \ge 0.90$$
+* **Operational Logic:** If the Red Team identifies 10 issues (logic flaws, rule violations, or security risks) and the Planner only addresses 8 in the next iteration, the score is $0.80$. The system will **block** execution and force another `plan -> review` cycle until 90% of issues are resolved.
+
+---
+
+## 3. Entropy Threshold (`entropy_threshold`)
+
+Located in the security block, this governs the **Secret Sanitization Pipeline**.
+
+* **Recommended Value:** `4.5` (bits per character)
+* **Technical Justification:**
+    * Standard English text and code typically fall between $1.5$ and $3.5$ bits of entropy.
+    * Cryptographic keys, API tokens, and high-randomness strings usually exceed $4.0$. 
+    * Setting this to `4.5` allows the system to automatically flag and redact potential secrets before they are sent to the Gemini API for enrichment or planning.
+
+---
+
+## 4. Architectural Impact Threshold (`impact_ratio`)
+
+This threshold determines when a module is classified as a **Core Module**, triggering stricter governance rules.
+
+* **Parameters:**
+    * `core_modules_count`: Top `N` modules by dependent count.
+    * `max_dependents_drift`: `0.20` (20%).
+* **Governance Rule:** If a task increases the number of dependents for a module by more than 20% in a single plan, `arc review` will flag it as **"Architectural Bloat"** and require a manual override or a higher convergence score ($0.95$).
+
+---
+
+### Revised `.nomos-config.json` Template
+
+```json
+{
+  "project_name": "nomos-arc.ai",
+  "version": "0.1.0",
+  "thresholds": {
+    "semantic_search": 0.70,
+    "convergence": 0.90,
+    "security_entropy": 4.5,
+    "impact_drift_limit": 0.20
+  },
+  "models": {
+    "indexing": "gemini-embedding-001",
+    "mapping": "gemini-1.5-flash",
+    "orchestration": "gemini-1.5-pro"
+  },
+  "governance": {
+    "enforce_shadow_branch": true,
+    "require_certification": true,
+    "auto_retry_iterations": 3
+  }
+}
+```
+