@nomos-arc/arc 0.1.0

package/docs/verification/verification-arc-ar.md

@@ -0,0 +1,560 @@
+# nomos-arc.ai Verification Architecture
+
+> ### *Compiler for AI Intent*
+>
+> **Engineering Integrity over Stochastic Generation**
+> Specification Version: 1.0 — Draft
+> Status: Phase 2 Architectural Manifesto
+> Last Updated: 2026-04-12
+
+---
+
+## 0. Document Purpose
+
+هذا المستند يوثّق **الميثاق المعماري** لمرحلة Phase 2 من `nomos-arc.ai`. ينقل المشروع من كونه أداة CLI مساعدة إلى **نظام حوكمة هندسية (Engineering Governance System)** يوفّر طبقة تحقق حتمية (Verifiable Layer) فوق المولدات الاحتمالية (LLMs).
+
+هذا المستند ليس خطة تنفيذ. هو **Specification** يحدد الحدود الدلالية والرياضية للنظام، ويُستخدم كمرجع لأي قرار تصميمي أو تنفيذي لاحق.
+
+---
+
+## 1. Foundational Philosophy
+
+### 1.1 The Stochastic-Deterministic Duality
+
+المولدات اللغوية الكبرى (LLMs) هي بطبيعتها أنظمة **Stochastic**:
+
+$$P(t_n \mid t_1, t_2, \ldots, t_{n-1})$$
+
+حيث كل توكن ناتج هو توزيع احتمالي مشروط بما سبقه. هذا يعني أن أي مخرَج من نموذج LLM هو **عيّنة (sample)** من فضاء ممكنات، وليس إثباتاً.
+
+`nomos-arc.ai` يُبنى على مسلّمة معاكسة: **الهندسة البرمجية تتطلب ضمانات قابلة للتحقق**. لذلك، دور nomos-arc ليس توليد الكود، بل **فرض قيود حتمية على المخرجات الاحتمالية**:
+
+$$\text{Output}_{\text{final}} = \mathcal{V}(\text{LLM}(\text{Intent}))$$
+
+حيث $\mathcal{V}$ هو **Verifier Function** حتمية لا تقبل إلا ما يحقق مجموعة القيود $\mathcal{C}$.
+
+### 1.2 Terminology: "Verifiable" not "Exact"
+
+الـ **Exactness** في علم الحاسوب مفهوم مقيّد بـ Formal Methods (Coq, Agda, TLA+)، ومكلفة عملياً. بدلاً من ذلك، يتبنى هذا النظام مصطلح **Verifiable**، أي:
+
+> إن كل مخرَج يخضع لمجموعة قيود قابلة للتحقق آلياً، ويُرفض ما يخالفها.
+
+هذا يعني أن ما نضمنه ليس "الصحة الدلالية المطلقة"، بل **Constraint Conformance**.
+
+### 1.3 Role Assignment
+
+| الدور | الكيان | الطبيعة |
+|------|--------|---------|
+| **Generator** | LLM (Gemini 1.5 Pro) | Stochastic |
+| **Validator** | nomos-arc Governance Core | Deterministic |
+| **Profiler** | Risk Profiler (async) | Statistical (separated) |
+
+الانفصال الصارم بين هذه الأدوار هو **العمود الفقري** للمعمارية.
+
+---
+
+## 2. Core Architectural Principles
+
+### 2.1 Principle I — Constraint Conformance over Output Correctness
+
+النظام لا يحكم على "صحة" الكود، بل على **مطابقته للقيود المعلنة** (structural, syntactic, behavioral).
+
+### 2.2 Principle II — Separation of Planning and Execution
+
+الفشل التقليدي لأدوات AI البرمجية ينبع من دمج **التخطيط** و **التنفيذ** في طلب واحد. `nomos-arc` يفصلهما:
+
+- **Planning Phase**: يُنتج **Contract** (عقد نية).
+- **Validation Gate**: يتحقق من العقد قبل أي توليد كود.
+- **Execution Phase**: لا يبدأ إلا بعد إجازة العقد.
+
+### 2.3 Principle III — Baseline-Relative Verification
+
+النظام لا يطلب "الكمال المطلق"، بل **ألّا يُسوَّأ الوضع**:
+
+$$\text{Accept}(S_{\text{after}}) \iff \Delta(S_{\text{before}}, S_{\text{after}}) \leq 0$$
+
+حيث $\Delta$ دالة تقيس تدهور الحالة (errors, warnings, failing tests). هذا يسمح باستخدام nomos-arc لإصلاح مشاريع مكسورة أصلاً دون أن يرفضها الـ Preflight.
+
+### 2.4 Principle IV — Probabilistic Inputs, Deterministic Gates
+
+البيانات الإحصائية (Risk Profiler, Pattern Mining) تُستخدم كـ **مدخلات** لضبط العتبات، لكن **البوابات نفسها** تبقى حتمية. لا مكان للعشوائية في مسار القرار النهائي.
+
+---
+
+## 3. Confidence-Tiered Rule System
+
+### 3.1 Rule Source Taxonomy
+
+| Source | Authority | Example |
+|--------|-----------|---------|
+| **Declared** | المستخدم يكتبها يدوياً (`rules/global.md`, `rules/domain/*.md`) | "ممنوع استخدام `any`" |
+| **Derived** | nomos-arc يستخرجها من `project_map.json` عبر Pattern Mining | "كل Controllers ترجع `ResponseDTO`" |
+| **Inferred** | nomos-arc يستنتجها من Co-Change History | "هذا الملف يتغير مع ذاك دائماً" |
+
+### 3.2 Confidence Function
+
+لأي نمط مرشح $p$، تُحسب درجة الثقة عبر:
+
+$$\text{Conf}(p) = \frac{|\{x \in \mathcal{X} : p(x) = \text{true}\}|}{|\mathcal{X}|}$$
+
+حيث $\mathcal{X}$ هو مجموعة الكيانات ذات الصلة (مثلاً: كل دوال الـ Controllers).
+
+### 3.3 Tier Assignment
+
+$$\text{Tier}(p) = \begin{cases}
+\text{Hard Rule} & \text{if } \text{Conf}(p) \geq 0.90 \\
+\text{Soft Rule} & \text{if } 0.70 \leq \text{Conf}(p) < 0.90 \\
+\text{Observation} & \text{if } \text{Conf}(p) < 0.70
+\end{cases}$$
+
+| Tier | Enforcement | Effect on Score |
+|------|-------------|-----------------|
+| **Hard Rule** | Auto-enforced | Violation → Hard Fail |
+| **Soft Rule** | Warned + penalized | Violation → $-0.1$ to $-0.2$ per occurrence |
+| **Observation** | Informational only | No scoring impact — feeds Planner context |
+
+هذا التدرج يمنع **Architectural Stagnation**: أنماط الأقلية المشروعة (refactors) لا تُكبت، لكنها تُوثَّق.
+
+### 3.4 Threshold Calibration
+
+عتبات 0.90 و 0.70 افتراضية. يجب أن تكون قابلة للضبط عبر `.nomos-config.json`:
+
+```json
+{
+  "governance": {
+    "hard_rule_threshold": 0.90,
+    "soft_rule_threshold": 0.70,
+    "min_sample_size": 10
+  }
+}
+```
+
+`min_sample_size` يمنع اشتقاق قواعد من عينات صغيرة جداً (ضجيج إحصائي).
+
+---
+
+## 4. AST Projection Model
+
+### 4.1 Problem Statement
+
+الـ Pre-Execution Validation على الخطة يواجه مشكلة **Chicken-and-Egg**: الخطة قد تشير إلى رموز (symbols) غير موجودة بعد لأنها ستُنشَأ ضمن نفس الخطة.
+
+### 4.2 Symbol Reference Classification
+
+عند تحليل العقد (Contract)، يُصنَّف كل مرجع إلى رمز في إحدى ثلاث فئات:
+
+$$\text{Ref}(s) \in \{\text{Existing}, \text{Declared}, \text{Forward}\}$$
+
+| Category | Validation Source |
+|----------|-------------------|
+| **Existing** | يُتحقق منه في الـ **Current AST** (من `project_map.json`) |
+| **Declared** | تعريف جديد ضمن نفس الخطة — يُضاف إلى **Projected AST** |
+| **Forward** | مرجع إلى رمز سيُعرَّف لاحقاً ضمن نفس الخطة — يُتحقق منه مقابل الـ **Projected AST** |
+
+### 4.3 Projected AST Construction
+
+$$\text{AST}_{\text{projected}} = \text{AST}_{\text{current}} \oplus \text{Declared}(\text{Plan})$$
+
+حيث $\oplus$ عملية دمج تُضيف التعريفات الجديدة قبل تحقق المراجع الأمامية. هذه البنية تشبه فلسفياً **Virtual DOM** في React — طبقة وسيطة بين النية والتطبيق الفعلي.
+
+### 4.4 Hallucination Detection
+
+$$\text{Hallucinated}(s) \iff \text{Ref}(s) = \text{Existing} \land s \notin \text{AST}_{\text{current}}$$
+
+عند اكتشاف هلوسة، يُعاد العقد إلى الـ Planner مع رسالة محددة:
+
+```
+Planner claimed: AuthService.validate()
+AST evidence: AuthService has methods [verify, revoke, refresh]
+Action: Re-plan with corrected symbol reference
+```
+
+---
+
+## 5. Dynamic Convergence Threshold
+
+### 5.1 Blast Radius Definition
+
+لأي ملف $f$، الـ Blast Radius هو عدد الكيانات التي تعتمد عليه بشكل مباشر أو غير مباشر:
+
+$$BR(f) = |\{g \in \mathcal{G} : g \xrightarrow{*} f\}|$$
+
+حيث $\mathcal{G}$ هو Dependency Graph و $\xrightarrow{*}$ هو الإغلاق التعدّي (transitive closure) لعلاقة الاعتماد.
+
+### 5.2 Convergence Threshold Formula
+
+$$\theta(f) = \theta_{\text{base}} + \alpha \cdot \log(1 + BR(f)) + \beta \cdot R(f)$$
+
+| Symbol | Meaning | Default |
+|--------|---------|---------|
+| $\theta_{\text{base}}$ | العتبة الأساسية | $0.85$ |
+| $\alpha$ | معامل حساسية الـ Blast Radius | $0.02$ |
+| $\beta$ | معامل حساسية الـ Risk Profile | $0.05$ |
+| $R(f)$ | درجة الخطر من Risk Profiler (انظر §7) | $\in [0, 1]$ |
+
+مع تطبيق سقف: $\theta(f) \leq 0.99$ لتجنب الاستحالة العملية.
+
+**المعنى العملي:**
+- ملف بلا dependents ومستقر → $\theta \approx 0.85$
+- ملف بـ 50 dependent ومستقر → $\theta \approx 0.93$
+- ملف بـ 50 dependent وغير مستقر → $\theta \approx 0.98$
+
+---
+
+## 6. The 8-Step Orchestration Pipeline
+
+### 6.1 Pipeline Overview
+
+$$\text{Task} \xrightarrow{S_1} \text{Baseline} \xrightarrow{S_2} \text{Contract} \xrightarrow{S_3} \text{Validated Contract} \xrightarrow{S_4} \text{Candidate} \xrightarrow{S_5} \text{Runnable} \xrightarrow{S_6} \text{Scored} \xrightarrow{S_7} \text{Delta-Checked} \xrightarrow{S_8} \text{Certified}$$
+
+### 6.2 Step-by-Step Specification
+
+#### **Step 1: Baseline Capture**
+
+**Input:** Current repository state
+**Output:** `baseline.json`
+
+يلتقط snapshot حتمي للحالة الراهنة:
+
+```json
+{
+  "timestamp": "ISO-8601",
+  "compile_errors": 0,
+  "type_errors": 3,
+  "lint_warnings": 12,
+  "lint_errors": 0,
+  "test_pass_rate": 0.87,
+  "test_count": 367,
+  "hash": "sha256:..."
+}
+```
+
+لا يقرأ Git history. سريع، خفيف، deterministic.
+
+#### **Step 2: Contract Drafting**
+
+**Input:** Task + Rules + Context + Risk Profile
+**Output:** Structured Contract (JSON)
+
+الـ LLM يُنتج "نية" مهيكلة، لا كود:
+
+```json
+{
+  "intent": "Add rate limiting to auth endpoints",
+  "affected_modules": ["src/auth/*.ts"],
+  "symbol_changes": [
+    { "type": "add", "symbol": "RateLimiter", "kind": "class" },
+    { "type": "modify", "symbol": "AuthService.login", "kind": "method" }
+  ],
+  "expected_delta": {
+    "files_modified": 2,
+    "files_added": 1
+  }
+}
+```
+
+#### **Step 3: Contract Validation Gate**
+
+**Input:** Contract + Current AST + Derived Rules
+**Output:** Pass / Fail-with-feedback
+
+يُطبّق:
+1. **AST Projection** (§4) للتحقق من صحة المراجع
+2. **Hard Rules Check** (§3) لرفض الانتهاكات المعلومة مسبقاً
+3. **Structural Feasibility**: هل الـ `affected_modules` موجودة فعلاً؟
+
+إن فشل → إعادة للـ Planner مع Feedback محدد (max $N$ iterations).
+
+#### **Step 4: Execution**
+
+**Input:** Validated Contract
+**Output:** Shadow Worktree with generated code
+
+يحدث في **git worktree** معزول. لا تأثير على الـ main branch.
+
+#### **Step 5: Hard Gates**
+
+**Input:** Candidate code
+**Output:** Compiler + Critical Linter verdict
+
+$$\text{Gate}_{\text{hard}} = \bigwedge_{g \in G_H} g(\text{code})$$
+
+حيث $G_H$ هي البوابات الصارمة: `tsc --noEmit`, `eslint --max-warnings=0 --rule-severity=error`, critical static analysis.
+
+**فشل → عودة للـ Planner أو Discard.** لا يُصرف توكنز على Soft Gates.
+
+#### **Step 6: Soft Gates + Scoring**
+
+**Input:** Code that passed Hard Gates
+**Output:** Composite Score $\in [0, 1]$
+
+$$\text{Score} = w_1 \cdot S_{\text{AI}} + w_2 \cdot S_{\text{lint}} + w_3 \cdot S_{\text{coverage}} + w_4 \cdot S_{\text{style}}$$
+
+مع:
+- $S_{\text{AI}}$: Reviewer AI score $\in [0, 1]$
+- $S_{\text{lint}} = 1 - \frac{\text{warnings}}{\text{warning\_budget}}$
+- $S_{\text{coverage}}$: نسبة التغطية للكود الجديد
+- $S_{\text{style}}$: مطابقة الـ Soft Rules
+- $\sum w_i = 1$
+
+#### **Step 7: Delta Comparison**
+
+**Input:** Baseline + Candidate state + Original Contract
+**Output:** Delta verdict
+
+يُتحقق من ثلاثة أبعاد:
+
+**(أ) No Regression:**
+$$\Delta_{\text{state}} = S_{\text{after}} - S_{\text{baseline}} \leq 0$$
+
+**(ب) Plan Conformance:**
+$$\Delta_{\text{plan}} = |\text{expected\_delta} - \text{actual\_delta}| \leq \epsilon$$
+
+انحراف كبير عن `expected_delta` في العقد → فشل (ربما الـ AI فعل أكثر أو أقل مما وعد).
+
+**(ج) Improvement Direction:** إن كانت المهمة إصلاحية (fix task)، يجب أن يكون $\Delta_{\text{state}} < 0$ فعلياً، لا مجرد $\leq 0$.
+
+#### **Step 8: Certificate Issuance**
+
+**Input:** All prior step artifacts
+**Output:** `certificate.json` (signed)
+
+```json
+{
+  "task_hash": "sha256:...",
+  "contract_hash": "sha256:...",
+  "diff_hash": "sha256:...",
+  "gates_passed": ["ast_projection", "hard_gates", "soft_gates", "delta"],
+  "score": 0.94,
+  "threshold_required": 0.91,
+  "iterations": 3,
+  "baseline_ref": "sha256:...",
+  "verifiable_claims": [
+    "No new compile errors",
+    "No hard rule violations",
+    "Expected delta matches actual delta (±1 file)"
+  ]
+}
+```
+
+الشهادة **لا تدّعي صحة دلالية**. تدّعي **مطابقة قيود محددة**.
+
+### 6.3 Conditional Execution Invariant
+
+**قاعدة صارمة:** Step $S_{i+1}$ لا يُنفَّذ إلا إذا نجح $S_i$. هذا يحمي من صرف موارد (API calls, compute) على مخرجات معطوبة.
+
+---
+
+## 7. Risk Profiler (Asynchronous Layer)
+
+### 7.1 Separation Rationale
+
+الـ Risk Profiler **ليس جزءاً من الـ Pipeline التنفيذي**. هو طبقة مستقلة:
+
+- **Pipeline** = synchronous, per-task, deterministic
+- **Risk Profiler** = asynchronous, periodic, statistical
+
+الدمج بينهما يُحوّل كل `arc run` إلى عملية Git log analysis، وهذا يهدم تجربة المستخدم على المشاريع الكبيرة.
+
+### 7.2 Architecture
+
+```
+┌─────────────────────┐
+│   Risk Profiler     │  Async, periodic (daily / on-demand)
+│                     │  Outputs: risk_profile.json
+└──────────┬──────────┘
+           │ consumed by
+           ↓
+┌─────────────────────────────────────────────┐
+│         8-Step Pipeline (Sync)              │
+│  S2: Planner reads risk context             │
+│  S3: Threshold $\theta(f)$ uses $R(f)$      │
+│  S6: Scoring weights modulated              │
+└─────────────────────────────────────────────┘
+```
+
+### 7.3 Core Metrics
+
+| Metric | Formula | Data Source |
+|--------|---------|-------------|
+| **Churn Rate** | $C(f) = \frac{\|\text{commits}_{f, \Delta t}\|}{\Delta t}$ | `git log --follow` |
+| **Revert Density** | $RD(f) = \frac{\|\text{reverted commits}_f\|}{\|\text{commits}_f\|}$ | `git log --grep=revert` |
+| **Bug-Fix Ratio** | $BF(f) = \frac{\|\text{fix-tagged commits}_f\|}{\|\text{commits}_f\|}$ | commit message parsing |
+| **Co-Change Coupling** | $CC(f_i, f_j) = \frac{\|\text{commits containing both}\|}{\|\text{commits containing either}\|}$ (Jaccard) | `git log` pair analysis |
+| **Ownership Dilution** | $OD(f) = \frac{H(\text{authors}_f)}{\log\|\text{authors}_f\|}$ (normalized entropy) | `git blame` |
+
+### 7.4 Composite Risk Score
+
+$$R(f) = \sigma\left( \gamma_1 \cdot C(f) + \gamma_2 \cdot RD(f) + \gamma_3 \cdot BF(f) + \gamma_4 \cdot OD(f) \right)$$
+
+حيث $\sigma$ هي دالة sigmoid للحصول على $R(f) \in [0, 1]$. أوزان $\gamma_i$ قابلة للضبط.
+
+### 7.5 Co-Change as Implicit Coupling Detector
+
+$CC(f_i, f_j) > 0.80$ دون وجود `import` أو dependency ظاهر في الـ AST يُشير إلى **اعتماد ضمني خفي** — غالباً اتفاقيات غير مصرَّح بها، مخطط بيانات مشترك، أو ثابت مكرر. هذا النوع من الاقتران لا يراه الـ AST، لكنه يكسر عند التعديل.
+
+### 7.6 Probabilistic Outputs, Never Verdicts
+
+النتائج تُصاغ كـ **احتمالات**، لا أحكام:
+
+> ❌ "Module X is fragile"
+> ✅ "Module X has 73% regression likelihood based on 6-month history (n=47 commits)"
+
+هذا يحفظ وعد **Verifiable**: الحقائق الحتمية تبقى في الـ Pipeline، الإحصائيات في الـ Profiler، ولكل دوره.
+
+---
+
+## 8. Incremental Map Invalidation
+
+### 8.1 Problem
+
+الـ `project_map.json` يُبنى حالياً عبر `arc map` كعملية كاملة (full scan). بعد Phase 2، بعد كل `arc apply` ناجح، يجب تحديث الخريطة. إعادة الـ scan الكامل على مشروع كبير = **seconds to minutes latency**.
+
+### 8.2 Incremental Scanner Design
+
+$$\text{AST}_{\text{new}} = (\text{AST}_{\text{old}} \setminus \text{Nodes}(F_{\text{changed}})) \cup \text{Parse}(F_{\text{changed}})$$
+
+حيث $F_{\text{changed}}$ هي الملفات المُعدَّلة في الـ apply.
+
+**Invalidation Cascade:**
+1. احذف العُقد الخاصة بـ $F_{\text{changed}}$ من الـ Graph
+2. أعد parsing لهذه الملفات فقط
+3. أعد بناء الـ edges الصادرة من/إلى هذه الملفات
+4. أعد حساب الـ Blast Radius للعُقد المتأثرة فقط (لا الكل)
+
+### 8.3 Cache Consistency Guarantee
+
+بعد أي `arc apply`:
+$$\text{Hash}(\text{AST}_{\text{new}}) = \text{Hash}(\text{FullScan}(\text{repo}))$$
+
+يجب أن يكون هناك **integrity test** دوري يُقارن المخرجين للتأكد من عدم انحراف الـ incremental update عن الـ full scan.
+
+---
+
+## 9. System-Level Invariants
+
+النظام يُلزَم بهذه الثوابت تحت كل الظروف:
+
+**I1 — No Generation Without Validation:**
+$$\nexists\, \text{code output} \text{ such that } \text{Contract Validation} = \text{Fail} \land \text{Generation proceeds}$$
+
+**I2 — No Scoring Without Hard Gates:**
+$$\text{Score computed} \implies \text{Hard Gates} = \text{Pass}$$
+
+**I3 — No Apply Without Delta Check:**
+$$\text{Merge to main} \implies \Delta_{\text{state}} \leq 0 \land \Delta_{\text{plan}} \leq \epsilon$$
+
+**I4 — No Certificate Without Full Pipeline:**
+$$\text{Certificate issued} \implies \bigwedge_{i=1}^{8} S_i = \text{Pass}$$
+
+**I5 — Probabilistic ∉ Decision Path:**
+القرارات الحتمية (pass/fail, merge/reject) لا تعتمد مباشرة على قيم احتمالية. الإحصائيات تُعدّل **عتبات** البوابات، لا تستبدلها.
+
+---
+
+## 10. Implementation Roadmap
+
+### Phase 2.1 — Governance Core (MVP)
+- [ ] Step 1: Baseline Capture (`arc baseline`)
+- [ ] Step 7: Delta Comparison
+- [ ] Basic Certificate fields extension
+- **Rationale:** أصغر scope، قيمة فورية، يحوّل الـ apply من "trust" إلى "evidence-based".
+
+### Phase 2.2 — Contract Validation
+- [ ] Step 2: Structured Contract schema
+- [ ] Step 3: AST Projection + Hard Rule checking
+- [ ] Hallucination feedback loop
+- **Rationale:** يمنع ~80% من أخطاء LLM قبل توليد الكود.
+
+### Phase 2.3 — Dynamic Thresholds
+- [ ] Blast Radius computation from existing graph
+- [ ] $\theta(f)$ formula integration
+- **Rationale:** يستخدم بيانات متوفرة أصلاً؛ تعديل scoring logic فقط.
+
+### Phase 2.4 — Auto-Derived Rules
+- [ ] Pattern Mining engine on `project_map.json`
+- [ ] Confidence-tiered rule emission
+- [ ] Soft/Hard/Observation categorization
+- **Rationale:** يقلل الحاجة لكتابة rules يدوياً.
+
+### Phase 2.5 — Risk Profiler
+- [ ] Git history analyzer
+- [ ] Core metrics computation
+- [ ] `risk_profile.json` emission
+- [ ] Integration with $R(f)$ in $\theta(f)$
+- **Rationale:** أكبر scope، يتطلب استقرار باقي الطبقات.
+
+### Phase 2.6 — Incremental Map
+- [ ] Incremental AST scanner
+- [ ] Invalidation cascade
+- [ ] Consistency verification tests
+- **Rationale:** optimization؛ لا يُحسّن الوظيفة، يُحسّن الأداء.
+
+---
+
+## 11. What This System Does *Not* Claim
+
+الصدق الهندسي يتطلب تحديد الحدود:
+
+- **لا يضمن الصحة الدلالية** (semantic correctness). كود يمر بكل البوابات قد يكون منطقياً خاطئاً.
+- **لا يستبدل المراجعة البشرية** للمهام عالية المخاطر.
+- **لا يُزيل الـ hallucination** تماماً — يقلله بشكل ملموس عبر AST Projection.
+- **لا يُنتج proofs رياضية** بمعنى Formal Verification. يُنتج **evidence** قابل للتدقيق.
+- **لا يصلح لمشاريع بلا tests ولا lint rules** — النظام يتغذى على مخرجات أدوات قائمة.
+
+---
+
+## 12. Positioning & Terminology
+
+### 12.1 Headline
+
+`nomos-arc.ai` في ضوء هذا الميثاق ليس "أداة AI برمجية أخرى". هو:
+
+> # **Compiler for AI Intent**
+>
+> طبقة تحقق تجبر المخرجات الاحتمالية للـ LLMs على الالتزام بعقود هندسية قابلة للتحقق آلياً، بحيث يصبح كل تغيير كود **evidence-backed** لا **trust-based**.
+
+فئة المنتج الأقرب: **Professional Tooling** (بجوار debuggers, profilers, static analyzers)، لا **AI Assistants**.
+
+### 12.2 Layered Terminology
+
+المصطلحات ليست قابلة للتبديل. كل طبقة لها مفرداتها:
+
+| Layer | Term | Usage |
+|-------|------|-------|
+| **Marketing / Positioning** | *Engineering Integrity System* | يوصّل القيمة للمطور: "كودك نزيه، موثق، غير ملوث بهلوسة AI" |
+| **Technical / Architectural** | *Verification Layer* / *Verifiable Pipeline* | يوصّل الدقة التقنية للمهندسين؛ يطابق ما يفعله النظام فعلاً |
+| **Code / Internal** | `src/core/governance/` | اسم موديول داخلي يجمع rules + validators + audit emitter |
+| **Conceptual / Headline** | *Compiler for AI Intent* | metaphor تواصلية تخلق توقعات صحيحة (deterministic, error-before-runtime, toolchain-native) |
+
+**قاعدة الاستخدام:** لا تستخدم "Governance" في التواصل الخارجي (مستندات، README، pitch). احتفظ بها كاسم subsystem داخلي فقط. استخدم **Verification** للأوصاف التقنية، و **Integrity** للقيمة، و **Compiler for AI Intent** كعنوان رئيسي.
+
+---
+
+## Appendix A — Symbol Reference Table
+
+| Symbol | Meaning |
+|--------|---------|
+| $\mathcal{V}$ | Verifier Function |
+| $\mathcal{C}$ | Constraint Set |
+| $\text{Conf}(p)$ | Rule confidence score |
+| $BR(f)$ | Blast Radius of file $f$ |
+| $R(f)$ | Risk score of file $f$ from Risk Profiler |
+| $\theta(f)$ | Convergence threshold for file $f$ |
+| $\Delta$ | Delta between two states |
+| $\oplus$ | AST merge operator |
+| $S_i$ | Pipeline Step $i$ |
+
+---
+
+## Appendix B — Related Documents
+
+- [governance-overview.md](./governance-overview.md) — Original philosophical framing
+- [../dev_overview.md](../dev_overview.md) — Project overview
+- [../how_it_works.md](../how_it_works.md) — Current Phase 1 mechanics
+- [../integrity-gate/](../integrity-gate/) — Existing integrity certificate design
+- [../map/](../map/) — Dependency graph specification
+
+---
+
+*End of Specification v1.0*