@nomos-arc/arc 0.1.0

package/docs/verification/verification-architecture.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
+
+This document codifies the **architectural manifesto** for Phase 2 of `nomos-arc.ai`. It elevates the project from a CLI helper into an **Engineering Integrity System** that provides a deterministic **Verifiable Layer** over stochastic generators (LLMs).
+
+This is not an implementation plan. It is a **Specification** defining the semantic and mathematical boundaries of the system, to be referenced by every subsequent design or implementation decision.
+
+---
+
+## 1. Foundational Philosophy
+
+### 1.1 The Stochastic-Deterministic Duality
+
+Large Language Models (LLMs) are inherently **stochastic** systems:
+
+$$P(t_n \mid t_1, t_2, \ldots, t_{n-1})$$
+
+Each emitted token is a conditional probability distribution over prior context. Therefore, any LLM output is a **sample** drawn from a space of possibilities — never a proof.
+
+`nomos-arc.ai` is built on the inverse axiom: **software engineering demands verifiable guarantees**. The role of nomos-arc is not to generate code, but to **impose deterministic constraints on probabilistic outputs**:
+
+$$\text{Output}_{\text{final}} = \mathcal{V}(\text{LLM}(\text{Intent}))$$
+
+where $\mathcal{V}$ is a deterministic **Verifier Function** that accepts only outputs satisfying the constraint set $\mathcal{C}$.
+
+### 1.2 Terminology: "Verifiable" not "Exact"
+
+**Exactness** in computer science is a concept bounded by Formal Methods (Coq, Agda, TLA+), and is practically expensive. Instead, this system adopts the term **Verifiable**:
+
+> Every output is subject to a machine-checkable constraint set, and any violation is rejected.
+
+What we guarantee is therefore not "absolute semantic correctness" — it is **Constraint Conformance**.
+
+### 1.3 Role Assignment
+
+| Role | Entity | Nature |
+|------|--------|--------|
+| **Generator** | LLM (Gemini 1.5 Pro) | Stochastic |
+| **Validator** | nomos-arc Governance Core | Deterministic |
+| **Profiler** | Risk Profiler (async) | Statistical (separated) |
+
+The strict separation between these roles is the **backbone** of the architecture.
+
+---
+
+## 2. Core Architectural Principles
+
+### 2.1 Principle I — Constraint Conformance over Output Correctness
+
+The system does not judge the "correctness" of code; it judges **conformance to declared constraints** (structural, syntactic, behavioral).
+
+### 2.2 Principle II — Separation of Planning and Execution
+
+The classical failure mode of AI coding tools is conflating **planning** and **execution** in a single call. `nomos-arc` separates them:
+
+- **Planning Phase** — produces a **Contract** (an intent contract).
+- **Validation Gate** — verifies the contract before any code generation.
+- **Execution Phase** — begins only after the contract is approved.
+
+### 2.3 Principle III — Baseline-Relative Verification
+
+The system does not demand absolute perfection; it demands that **the state not regress**:
+
+$$\text{Accept}(S_{\text{after}}) \iff \Delta(S_{\text{before}}, S_{\text{after}}) \leq 0$$
+
+where $\Delta$ measures state degradation (errors, warnings, failing tests). This allows nomos-arc to be used for fixing already-broken projects without being rejected at Preflight.
+
+### 2.4 Principle IV — Probabilistic Inputs, Deterministic Gates
+
+Statistical data (Risk Profiler, Pattern Mining) is used as **input** to threshold calibration, but **the gates themselves** remain deterministic. Probabilistic values never sit on the final decision path.
+
+---
+
+## 3. Confidence-Tiered Rule System
+
+### 3.1 Rule Source Taxonomy
+
+| Source | Authority | Example |
+|--------|-----------|---------|
+| **Declared** | Written manually by the user (`rules/global.md`, `rules/domain/*.md`) | "Do not use `any`" |
+| **Derived** | Mined by nomos-arc from `project_map.json` via Pattern Mining | "All Controllers return `ResponseDTO`" |
+| **Inferred** | Inferred by nomos-arc from Co-Change History | "This file always changes with that one" |
+
+### 3.2 Confidence Function
+
+For any candidate pattern $p$, its confidence score is:
+
+$$\text{Conf}(p) = \frac{|\{x \in \mathcal{X} : p(x) = \text{true}\}|}{|\mathcal{X}|}$$
+
+where $\mathcal{X}$ is the relevant population (e.g. all Controller methods).
+
+### 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 |
+
+This tiering prevents **Architectural Stagnation**: legitimate minority patterns (refactors) are not suppressed, merely documented.
+
+### 3.4 Threshold Calibration
+
+The thresholds $0.90$ and $0.70$ are defaults. They must be configurable via `.nomos-config.json`:
+
+```json
+{
+  "governance": {
+    "hard_rule_threshold": 0.90,
+    "soft_rule_threshold": 0.70,
+    "min_sample_size": 10
+  }
+}
+```
+
+`min_sample_size` prevents rule derivation from tiny samples (statistical noise).
+
+---
+
+## 4. AST Projection Model
+
+### 4.1 Problem Statement
+
+Pre-execution validation on a plan faces a **chicken-and-egg** problem: a plan may reference symbols that do not yet exist, because they will be introduced by the plan itself.
+
+### 4.2 Symbol Reference Classification
+
+While analyzing the Contract, every symbol reference is classified into one of three categories:
+
+$$\text{Ref}(s) \in \{\text{Existing}, \text{Declared}, \text{Forward}\}$$
+
+| Category | Validation Source |
+|----------|-------------------|
+| **Existing** | Checked against the **Current AST** (from `project_map.json`) |
+| **Declared** | A new definition introduced by the plan — added to the **Projected AST** |
+| **Forward** | A reference to a symbol that will be defined later in the same plan — checked against the **Projected AST** |
+
+### 4.3 Projected AST Construction
+
+$$\text{AST}_{\text{projected}} = \text{AST}_{\text{current}} \oplus \text{Declared}(\text{Plan})$$
+
+where $\oplus$ is a merge operator that injects the new declarations before forward references are resolved. Conceptually, this structure resembles a **Virtual DOM** in React — an intermediate layer between intent and actual application.
+
+### 4.4 Hallucination Detection
+
+$$\text{Hallucinated}(s) \iff \text{Ref}(s) = \text{Existing} \land s \notin \text{AST}_{\text{current}}$$
+
+When a hallucination is detected, the Contract is returned to the Planner with a specific message:
+
+```
+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
+
+For any file $f$, the Blast Radius is the number of entities that depend on it directly or transitively:
+
+$$BR(f) = |\{g \in \mathcal{G} : g \xrightarrow{*} f\}|$$
+
+where $\mathcal{G}$ is the Dependency Graph and $\xrightarrow{*}$ is the transitive closure of the dependency relation.
+
+### 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}}$ | Base threshold | $0.85$ |
+| $\alpha$ | Blast Radius sensitivity coefficient | $0.02$ |
+| $\beta$ | Risk Profile sensitivity coefficient | $0.05$ |
+| $R(f)$ | Risk score from Risk Profiler (see §7) | $\in [0, 1]$ |
+
+A hard cap is applied: $\theta(f) \leq 0.99$, to avoid practical impossibility.
+
+**Operational meaning:**
+- A file with no dependents, stable → $\theta \approx 0.85$
+- A file with 50 dependents, stable → $\theta \approx 0.93$
+- A file with 50 dependents, unstable → $\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`
+
+Captures a deterministic snapshot of the present state:
+
+```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:..."
+}
+```
+
+Does not read Git history. Fast, lightweight, deterministic.
+
+#### **Step 2: Contract Drafting**
+
+**Input:** Task + Rules + Context + Risk Profile
+**Output:** Structured Contract (JSON)
+
+The LLM emits a structured **intent**, not code:
+
+```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
+
+Applies:
+1. **AST Projection** (§4) to verify reference validity.
+2. **Hard Rules Check** (§3) to reject pre-known violations.
+3. **Structural Feasibility:** do the declared `affected_modules` actually exist?
+
+On failure → return to Planner with targeted feedback (max $N$ iterations).
+
+#### **Step 4: Execution**
+
+**Input:** Validated Contract
+**Output:** Shadow worktree containing generated code
+
+Performed in an isolated **git worktree**. No effect on the 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})$$
+
+where $G_H$ is the set of strict gates: `tsc --noEmit`, `eslint --max-warnings=0 --rule-severity=error`, critical static analysis.
+
+**On failure → return to Planner or Discard.** No tokens are spent on 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}}$$
+
+with:
+- $S_{\text{AI}}$: Reviewer AI score $\in [0, 1]$
+- $S_{\text{lint}} = 1 - \frac{\text{warnings}}{\text{warning\_budget}}$
+- $S_{\text{coverage}}$: coverage ratio for new code
+- $S_{\text{style}}$: Soft Rule conformance
+- $\sum w_i = 1$
+
+#### **Step 7: Delta Comparison**
+
+**Input:** Baseline + Candidate state + Original Contract
+**Output:** Delta verdict
+
+Verified along three dimensions:
+
+**(a) No Regression:**
+$$\Delta_{\text{state}} = S_{\text{after}} - S_{\text{baseline}} \leq 0$$
+
+**(b) Plan Conformance:**
+$$\Delta_{\text{plan}} = |\text{expected\_delta} - \text{actual\_delta}| \leq \epsilon$$
+
+Any significant deviation from the contract's `expected_delta` → fail (the AI may have done more or less than promised).
+
+**(c) Improvement Direction:** For fix tasks, the delta must strictly improve: $\Delta_{\text{state}} < 0$, not merely $\leq 0$.
+
+#### **Step 8: Certificate Issuance**
+
+**Input:** Artifacts from all prior steps
+**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)"
+  ]
+}
+```
+
+The certificate **does not claim semantic correctness**. It claims **conformance to specific constraints**.
+
+### 6.3 Conditional Execution Invariant
+
+**Strict rule:** Step $S_{i+1}$ is never executed unless $S_i$ succeeded. This prevents spending resources (API calls, compute) on already-broken outputs.
+
+---
+
+## 7. Risk Profiler (Asynchronous Layer)
+
+### 7.1 Separation Rationale
+
+The Risk Profiler **is not part of the synchronous pipeline**. It is an independent layer:
+
+- **Pipeline** = synchronous, per-task, deterministic
+- **Risk Profiler** = asynchronous, periodic, statistical
+
+Merging them would turn every `arc run` into a Git log analysis operation — destroying user experience on large repositories.
+
+### 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)$$
+
+where $\sigma$ is a sigmoid, producing $R(f) \in [0, 1]$. Weights $\gamma_i$ are configurable.
+
+### 7.5 Co-Change as Implicit Coupling Detector
+
+$CC(f_i, f_j) > 0.80$ in the absence of any visible `import` or AST-level dependency suggests an **implicit hidden coupling** — likely an undocumented contract, shared schema, or duplicated constant. This class of coupling is invisible to the AST, yet breaks under modification.
+
+### 7.6 Probabilistic Outputs, Never Verdicts
+
+Outputs are phrased as **probabilities**, never verdicts:
+
+> ❌ "Module X is fragile"
+> ✅ "Module X has 73% regression likelihood based on 6-month history (n=47 commits)"
+
+This preserves the **Verifiable** promise: deterministic facts stay in the Pipeline, statistics stay in the Profiler — each in its own lane.
+
+---
+
+## 8. Incremental Map Invalidation
+
+### 8.1 Problem
+
+`project_map.json` is currently built by `arc map` as a full scan. Post-Phase-2, after every successful `arc apply`, the map must be updated. A full re-scan on a large project costs **seconds to minutes of 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}})$$
+
+where $F_{\text{changed}}$ is the set of files modified by the apply.
+
+**Invalidation Cascade:**
+1. Remove the nodes belonging to $F_{\text{changed}}$ from the Graph.
+2. Re-parse only those files.
+3. Rebuild edges originating from / pointing into those files.
+4. Recompute Blast Radius only for affected nodes (not the entire graph).
+
+### 8.3 Cache Consistency Guarantee
+
+After any `arc apply`:
+$$\text{Hash}(\text{AST}_{\text{new}}) = \text{Hash}(\text{FullScan}(\text{repo}))$$
+
+A periodic **integrity test** must compare both outputs to ensure the incremental path has not drifted from the full-scan ground truth.
+
+---
+
+## 9. System-Level Invariants
+
+The system must uphold the following invariants under all conditions:
+
+**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:**
+Deterministic decisions (pass/fail, merge/reject) never depend directly on probabilistic values. Statistics adjust gate **thresholds** — they never replace gates.
+
+---
+
+## 10. Implementation Roadmap
+
+### Phase 2.1 — Governance Core (MVP)
+- [ ] Step 1: Baseline Capture (`arc baseline`)
+- [ ] Step 7: Delta Comparison
+- [ ] Basic Certificate field extension
+- **Rationale:** Smallest scope, immediate value; shifts `apply` from "trust" to "evidence-based".
+
+### Phase 2.2 — Contract Validation
+- [ ] Step 2: Structured Contract schema
+- [ ] Step 3: AST Projection + Hard Rule checking
+- [ ] Hallucination feedback loop
+- **Rationale:** Eliminates ~80% of LLM errors before code generation.
+
+### Phase 2.3 — Dynamic Thresholds
+- [ ] Blast Radius computation from the existing graph
+- [ ] $\theta(f)$ formula integration
+- **Rationale:** Uses already-available data; scoring-logic modification only.
+
+### Phase 2.4 — Auto-Derived Rules
+- [ ] Pattern Mining engine on `project_map.json`
+- [ ] Confidence-tiered rule emission
+- [ ] Soft / Hard / Observation categorization
+- **Rationale:** Reduces the need for hand-written rules.
+
+### Phase 2.5 — Risk Profiler
+- [ ] Git history analyzer
+- [ ] Core metrics computation
+- [ ] `risk_profile.json` emission
+- [ ] Integration of $R(f)$ into $\theta(f)$
+- **Rationale:** Largest scope; depends on stability of prior layers.
+
+### Phase 2.6 — Incremental Map
+- [ ] Incremental AST scanner
+- [ ] Invalidation cascade
+- [ ] Consistency verification tests
+- **Rationale:** Optimization; improves performance, not functionality.
+
+---
+
+## 11. What This System Does *Not* Claim
+
+Engineering honesty requires stating the boundaries:
+
+- **Does not guarantee semantic correctness.** Code passing every gate may still be logically wrong.
+- **Does not replace human review** for high-risk tasks.
+- **Does not fully eliminate hallucination** — it measurably reduces it via AST Projection.
+- **Does not produce mathematical proofs** in the Formal Verification sense. It produces **auditable evidence**.
+- **Does not suit projects lacking tests or lint rules** — the system feeds on the outputs of existing tooling.
+
+---
+
+## 12. Positioning & Terminology
+
+### 12.1 Headline
+
+Under this manifesto, `nomos-arc.ai` is not "yet another AI coding tool". It is:
+
+> # **Compiler for AI Intent**
+>
+> A verification layer that forces probabilistic LLM outputs to conform to machine-checkable engineering contracts — making every code change **evidence-backed**, not **trust-based**.
+
+The closest product category: **Professional Tooling** (alongside debuggers, profilers, static analyzers), not **AI Assistants**.
+
+### 12.2 Layered Terminology
+
+Terminology is not interchangeable. Each layer has its own vocabulary:
+
+| Layer | Term | Usage |
+|-------|------|-------|
+| **Marketing / Positioning** | *Engineering Integrity System* | Conveys the value to the developer: "your code is sound, certified, free of AI hallucination" |
+| **Technical / Architectural** | *Verification Layer* / *Verifiable Pipeline* | Conveys technical precision to engineers; matches what the system actually does |
+| **Code / Internal** | `src/core/governance/` | Internal module name bundling rules + validators + audit emitter |
+| **Conceptual / Headline** | *Compiler for AI Intent* | A communication metaphor that creates correct expectations (deterministic, error-before-runtime, toolchain-native) |
+
+**Usage rule:** do not use "Governance" in external communication (docs, README, pitch). Keep it as an internal subsystem name only. Use **Verification** for technical prose, **Integrity** for value framing, and **Compiler for AI Intent** as the headline.
+
+---
+
+## 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*

package/docs/very_next.md

@@ -0,0 +1,52 @@
+بصفتي **CEO** و**Lead Architect**، أرى أننا قد انتهينا للتو من بناء "المحرك" و"نظام الملاحة" لـ **nomos-arc.ai**. لكي يكتمل المشروع في نفس الاتجاه الاستراتيجي (الرقابة، النزاهة، والفهم الشامل)، هناك 5 مسارات تطويرية ستحول هذه الأداة من "مساعد للمبرمج" إلى **"نظام تشغيل لإدارة المشاريع البرمجية"**:
+
+---
+
+## 1. بوابات الحوكمة الأوتوماتيكية (CI/CD Integrity Gates)
+بما أننا نمتلك الآن "خريطة دلالية" و"شهادة نزاهة"، يجب أن نمنع أي كود من الوصول للإنتاج إذا لم يحترم المعايير.
+* **المهمة:** تطوير **GitHub Action / GitLab CI Component**.
+* **الوظيفة:** عند عمل "Pull Request"، يقوم النظام بتشغيل `arc map` ومقارنته بالخريطة السابقة. إذا وجد انحرافاً معمارياً (**Architectural Drift**) أو كسرًا لعقد دلالي دون مراجعة، يتم إيقاف الـ Pipeline فوراً.
+* **الأثر:** تحويل nomos-arc من أداة "اختيارية" إلى "حارس بوابة" (Gatekeeper) إلزامي.
+
+## 2. البحث الدلالي العالمي (Global Semantic Search)
+حالياً، نحن نبحث عن "الرموز" (Symbols). الخطوة التالية هي البحث عن "المعنى" (Intent).
+* **المهمة:** دمج **Vector Embeddings** لخريطة المشروع.
+* **الوظيفة:** بدلاً من البحث عن كلمة `Payment` في الملفات، يمكنك سؤال الأداة: "أين يتم معالجة منطق استرداد الأموال في هذا المشروع؟".
+* **التقنية:** تحويل محتويات `project_map.json` و `.semantic.md` إلى متجهات (Vectors) مخزنة محلياً، مما يتيح استعلامات طبيعية (Natural Language Queries) عابرة للملفات.
+
+## 3. الربط الديناميكي (Static-to-Runtime Linkage)
+الخريطة الحالية "ساكنة" (Static). لكي تكتمل الصورة، يجب أن ترى الخريطة ما يحدث أثناء التشغيل.
+* **المهمة:** دمج بيانات **OpenTelemetry** أو سجلات الأخطاء (Logs).
+* **الوظيفة:** في خريطة `arc show map` التفاعلية، تظهر العقد (Nodes) التي تسبب أخطاء متكررة في بيئة الإنتاج بلون "وامض".
+* **الفائدة:** عند الضغط على ملف "أحمر" (عالي الخطورة)، ترى ليس فقط من يعتمد عليه كودياً، بل من تسبب في تعطيله برمجياً في آخر 24 ساعة.
+
+## 4. دعم تعدد اللغات (Polyglot Support)
+لكي يكون nomos-arc "منصة فهم شاملة"، يجب ألا يقتصر على TypeScript/JavaScript.
+* **المهمة:** إضافة Grammars لـ **Python, Go, Rust** في محرك `tree-sitter`.
+* **التحدي التقني:** ستحتاج لتحديث الـ `ImportResolver` ليفهم فلسفة كل لغة في إدارة التبعيات (مثل `go.mod` أو `requirements.txt`).
+
+## 5. مقياس "الدين التقني" (AI-Driven Technical Debt Scoring)
+تحويل الخريطة إلى أداة اتخاذ قرار للـ CTO والـ Project Manager.
+* **المهمة:** تنفيذ خوارزمية قياس جودة الكود الآلي.
+* **الرياضيات:** حساب مؤشر القابلية للصيانة ($MI$) لكل عقدة في الجراف:
+$$MI = \text{MAX}(0, (171 - 5.2 \ln(V) - 0.23(G) - 16.2 \ln(L)) \times 100 / 171)$$
+*حيث $V$ هو حجم Halstead، و $G$ هو التعقيد الدوري (Cyclomatic Complexity)، و $L$ هو عدد الأسطر.*
+* **النتيجة:** تلوين الخريطة بناءً على "الدين التقني". الملفات التي تحتاج "Refactoring" تظهر بوضوح للمديرين.
+
+---
+
+## ملخص خارطة الطريق القادمة (Strategic Roadmap)
+
+| المسار | الأداة/التقنية | الهدف الاستراتيجي |
+| :--- | :--- | :--- |
+| **Automation** | CI/CD Actions | فرض النزاهة المعمارية برمجياً. |
+| **Intelligence** | Vector DB (Local) | البحث بالمعنى وليس بالكلمة. |
+| **Observability** | OpenTelemetry | ربط الكود الساكن بحالة التشغيل الحية. |
+| **Expansion** | Tree-sitter Grammars | دعم كافة لغات البرمجة في المؤسسة. |
+| **Governance** | Tech Debt Metric | تحديد أولويات الإصلاح بناءً على أرقام حقيقية. |
+
+
+
+بصفتي CEO، أرى أن **المسار الأول (CI/CD Gates)** هو الأهم حالياً لأنه سيحول nomos-arc من "مشروع ممتع" إلى "بنية تحتية حيوية" للشركات.
+
+**أي من هذه المسارات تعتقد أنه يمثل "النقلة النوعية" التالية لـ nomos-arc.ai في سوق العمل؟**