mjolnir-qa 1.0.9 → 2.0.0

package/README.ar.md

@@ -1,384 +1,431 @@
 <div align="center">
 
-<img src="assets/readme/logo.png" alt="Mjölnir — Verification Trust Engine" width="800" />
+<img src="assets/readme/hero.svg" alt="Mjölnir. الاختبارات تخبرك بما نجح. Mjölnir يخبرك بما يمكنك الوثوق به." width="100%" />
 
-### اختباراتك تكذب عليك. نحن نُثبت ذلك.
+<br />
 
-**Verification Trust Engine لضمان الجودة.** يراجع Mjölnir أطقم الاختبارات
-وخطوط CI، ويُبلّغ عن درجة الجدارة، ويُظهر بدقة أين ينكسر الثقة.
+يعثر Mjölnir على الاختبارات التي لا يمكن أن تفشل وخطوط CI التي لا يمكن أن تتحول إلى الأحمر،<br />
+ثم يقيّم إلى أي حد يمكن الوثوق بالنتيجة، مع الدليل على كل نقطة.
 
-[![npm](https://img.shields.io/npm/v/mjolnir-qa.svg?style=flat-square&color=C19A34&labelColor=0A1119)](https://www.npmjs.com/package/mjolnir-qa)
-[![ci](https://img.shields.io/github/actions/workflow/status/Sergey-Bar/Mjolnir/ci.yml?branch=main&style=flat-square&label=ci&labelColor=0A1119)](https://github.com/Sergey-Bar/Mjolnir/actions/workflows/ci.yml)
-[![license](https://img.shields.io/badge/license-MIT-C19A34.svg?style=flat-square&labelColor=0A1119)](LICENSE)
-[![node](https://img.shields.io/badge/node-%E2%89%A5%2022.18-37ABBD.svg?style=flat-square&labelColor=0A1119)](https://nodejs.org)
-
-[English](README.md) | [简体中文](README.zh.md) | [繁體中文](README.zht.md) | [한국어](README.ko.md) | [Deutsch](README.de.md) | [Español](README.es.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Dansk](README.da.md) | [日本語](README.ja.md) | [Polski](README.pl.md) | [Русский](README.ru.md) | [Norsk](README.no.md) | [Português (Brasil)](README.br.md) | [ไทย](README.th.md) | [Türkçe](README.tr.md) | [Українська](README.uk.md) | [বাংলা](README.bn.md) | [Ελληνικά](README.gr.md) | [Tiếng Việt](README.vi.md) | [עברית](README.he.md) | العربية | [Bosanski](README.bs.md)
+<br />
 
-> 🤖 Machine-assisted translation. The [English README](README.md) is canonical. Last synced: 2026-09-08.
+[![npm](https://img.shields.io/npm/v/mjolnir-qa.svg?style=flat-square&color=1F6F7C&labelColor=0A1119)](https://www.npmjs.com/package/mjolnir-qa)
+[![downloads](https://img.shields.io/npm/dm/mjolnir-qa.svg?style=flat-square&color=1F6F7C&labelColor=0A1119)](https://www.npmjs.com/package/mjolnir-qa)
+[![ci](https://img.shields.io/github/actions/workflow/status/Sergey-Bar/Mjolnir/ci.yml?branch=main&style=flat-square&label=ci&labelColor=0A1119)](https://github.com/Sergey-Bar/Mjolnir/actions/workflows/ci.yml)
+[![coverage](https://img.shields.io/codecov/c/github/Sergey-Bar/Mjolnir?style=flat-square&color=1F6F7C&labelColor=0A1119&label=coverage)](https://codecov.io/gh/Sergey-Bar/Mjolnir)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Sergey-Bar/Mjolnir/badge)](https://scorecard.dev/viewer/?uri=github.com/Sergey-Bar/Mjolnir)
+[![license](https://img.shields.io/badge/license-MIT-1F6F7C.svg?style=flat-square&labelColor=0A1119)](LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A5%2022.18-1F6F7C.svg?style=flat-square&labelColor=0A1119)](https://nodejs.org)
 
 ```bash
 npx mjolnir-qa@latest
 ```
 
-**هل اختباراتك جديرة بالثقة؟**
+[شاهده وهو يعمل](#شاهده-وهو-يعمل) · [البدء السريع](#البدء-السريع) · [ما الذي يكتشفه](#ما-الذي-يكتشفه-mjölnir) · [الدرجة](#درجة-الجدارة) · [الأدلة](#نموذج-الأدلة) · [تحليل التشغيلات](#تحليل-تشغيلات-الاختبار) · [CI](#سلامة-ci) · [الوكلاء](#وكلاء-الذكاء-الاصطناعي) · [الأمان](#الثقة-والأمان) · [الحدود](#ما-لا-يستطيع-mjölnir-أن-يخبرك-به) · [التوثيق](#التوثيق)
+
+<details>
+<summary>اقرأ بلغة أخرى — 22 ترجمة</summary>
+
+[English](README.md) | [简体中文](README.zh.md) | [繁體中文](README.zht.md) | [한국어](README.ko.md) | [Deutsch](README.de.md) | [Español](README.es.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Dansk](README.da.md) | [日本語](README.ja.md) | [Polski](README.pl.md) | [Русский](README.ru.md) | [Norsk](README.no.md) | [Português (Brasil)](README.br.md) | [ไทย](README.th.md) | [Türkçe](README.tr.md) | [Українська](README.uk.md) | [বাংলা](README.bn.md) | [Ελληνικά](README.gr.md) | [Tiếng Việt](README.vi.md) | [עברית](README.he.md) | العربية | [Bosanski](README.bs.md)
+
+> 🤖 Machine-assisted translation. The [English README](README.md) is canonical. Last synced: 2026-09-15.
+
+<!-- Source hash: 3541b09e8d04 -->
 
-[شاهده يعمل](#-شاهده-يعمل) ·
-[البداية السريعة](#-البداية-السريعة) ·
-[ماذا يفحص](#-ماذا-يفحص-mjölnir) ·
-[التنقيط](#كيف-يعمل-التنقيط) ·
-[CI](#-تكامل-ci) · [الإعداد](#الإعداد) ·
-[الوثائق](#-الوثائق)
+</details>
 
 </div>
 
----
+<br />
+
+## علامة الصح الخضراء ادعاء، وليست دليلًا
+
+علامة الصح الخضراء تعني أن خط CI لم يفشل. لا تعني أن الاختبارات عملت، ولا أنها كان يمكن أن تفشل. كل واحدة من هذه تمر باللون الأخضر:
+
+- ‏`.only` بقي في commit فشغّل 3 اختبارات بدل 900
+- ‏`continue-on-error: true` على الـ job الذي كان يُفترض أن يمنع الدمج
+- ‏`|| true` بعد أمر الاختبار
+- اختبار لا يتحقق من أي شيء، أو جسمه فارغ
+- غلاف إعادة محاولة يحوّل فشلًا حقيقيًا إلى نجاح بالحظ
+- تقرير يرفعه الـ workflow لكنه لم يُنشأ قط
+- ‏sleep ثابت يُبقي حالة تسابق متماسكة
+
+لا يحوّل أيٌّ منها خط CI إلى الأحمر، وكل واحد منها يبدو مقصودًا عند المراجعة. لهذا تبقى. هذا Mjölnir يقرأ مثالًا حقيقيًا:
+
+<p align="center">
+  <img src="assets/readme/scan.svg" alt="‏workflow الـ CI في مستودع العرض، مقروءًا سطرًا بسطر. يعلّم Mjölnir كل نتيجة عند السطر الذي أبلغ عنه، مع قاعدتها وما الخطأ ومستوى الدليل ومعدل الإيجابيات الكاذبة المقيس لها." width="800" />
+</p>
+
+<sub>كل نتيجة أبلغ عنها فحص العرض لهذا الـ workflow، عند السطر الذي أبلغ عنه. مولَّد بواسطة `npm run docs:readme-brand` من [`demo-report.json`](assets/readme/demo-report.json) ومقفل ضد الانحراف في CI.</sub>
+
+**الوضع الصارم.** الكشف الأكثر عدوانية — `.only`، `continue-on-error`، الاختبارات الفارغة، إساءة إعادة المحاولة — تقع في مستوى الحجر الصحي. تعمل فقط مع `--strict` وتُ限定 بخطورة `info`: تُعلم، لكنها لا تُوقف أبدًا. الفحص الافتراضي (`npx mjolnir-qa@latest` بدون `--strict`) يغطي القواعد الأساسية والموسعة فقط. أضف `--strict` عندما تريد طبقة الاستشارات أيضًا.
+
+يقرأ Mjölnir مجموعة الاختبارات وملفات workflow الخاصة بـ CI، وتقرير تشغيل حقيقي إن وُجد. لا يشغّل اختباراتك، ولا يثبّت اعتمادياتك، ولا ينفّذ الشيفرة التي يفحصها. وعندما لا يملك دليلًا، يقول ذلك بدل أن يختلق ثقة:
+
+| الحالة                                                   | ما يبلّغ عنه Mjölnir                                       |
+| -------------------------------------------------------- | ---------------------------------------------------------- |
+| لم يُعثر على تعريفات اختبارات                            | الدرجة `null`، وتُعرض كـ **UNKNOWN**. لا 100 مختلقة أبدًا. |
+| لا يوجد خط أساس أو مراجعة قابلة للمقارنة                 | ‏**UNKNOWN**، مع ذكر السبب. لا 0 مفترضة أبدًا.             |
+| توقف الفحص قبل اكتماله (ميزانية الوقت، ملفات غير مقروءة) | ‏**PARTIAL**، رمز الخروج `2`. لا يُعرض أبدًا على أنه نظيف. |
+
+<p align="center">
+  <img src="assets/readme/how-it-works.svg" alt="كيف يعمل Mjölnir. يقرأ مجموعة الاختبارات وخط CI قراءة ساكنة، وتقرير تشغيل حقيقي عند وجوده. يزن كل نتيجة حسب مستوى دليلها ومستوى الثقة بها، حيث لا يصل إلى L3 حتى L5 إلا تشغيل حقيقي، وينتج نتائج ودرجة جدارة وبوابة CI برموز خروج مجمّدة. وفي حلقة الوكيل، يكتب الذكاء الاصطناعي الإصلاح ويعيد Mjölnir الفحص لإثباته." width="880" />
+</p>
+
+<sub>صُمّم لهذه الصفحة ويُعرض بمقياس 1:1. مولَّد بواسطة `npm run docs:readme-brand` ومقفل ضد الانحراف في CI؛ الدرجة والأعداد ومعرّف القاعدة تأتي من [`script.demo.json`](assets/video/script.demo.json) و[`demo-report.json`](assets/readme/demo-report.json) وسجل القواعد، ولا تُكتب يدويًا أبدًا. الصورة نفسها كملصق: [`architecture.svg`](assets/readme/architecture.svg).</sub>
+
+<br />
+
+## شاهده وهو يعمل
+
+فحص حقيقي لـ [`examples/demo-repo`](examples/demo-repo)، وهي مجموعة Playwright صغيرة مع workflow لـ CI. هنا ذهبت نقاطها:
+
+<p align="center">
+  <img src="assets/readme/terminal-hero.svg" alt="تفصيل الخصومات في Mjölnir: WORTHINESS 75/100 NEEDS WORK، والدرجة حسب الفئة، ومربع الخصومات حسب الخطورة، وقائمة FIX THIS FIRST" width="520" />
+</p>
+
+<sub>مولَّد بواسطة `npm run docs:hero` من فحص حقيقي ومقفل ضد الانحراف في CI. تقرير `--verbose` الكامل للفحص نفسه هو [`demo.svg`](assets/readme/demo.svg) (`npm run docs:demo`).</sub>
+
+<details>
+<summary><strong>شاهده</strong> — فحص، والإصلاح الذي يطبعه، وإعادة الفحص التي تثبته</summary>
 
-## 🎬 شاهده يعمل
+<br />
 
 <p align="center">
-  <img src="assets/readme/demo.svg" alt="تقرير --verbose الكامل لـ Mjölnir على مستودع تجريبي: WORTHINESS 75/100 NEEDS WORK، تفصيل تشخيصات بحسب الفئة، قائمة FIX THIS FIRST، وكل اكتشاف مع معرّف القاعدة ورقم السطر — عبر قواعد CI وPlaywright ونظافة الاختبارات وPython" width="900" />
+  <a href="assets/video/mjolnir-demo.mp4">
+    <img src="assets/video/mjolnir-demo-poster.png" alt="لقطة من تسجيل العرض: npx mjolnir-qa@latest يفحص مستودع العرض في نافذة طرفية" width="900" />
+  </a>
 </p>
 
-<sub>الناتج الكامل لـ `npx mjolnir-qa ./examples/demo-repo --verbose`
-معروض من المُبلِّغ الحقيقي — لا شيء مقتطع. يُعاد توليده بـ
-`npm run docs:demo`؛
-[`tests/demo-asset-reproducibility.spec.ts`](tests/demo-asset-reproducibility.spec.ts)
-يُسقط CI إذا انحرفت المخرجات عمّا تطبعه الأداة.</sub>
+<sub>رُسم إطارًا بإطار من فحص حقيقي بواسطة `npm run docs:video`؛ ولم يُسجَّل من الشاشة قط. اختر الإطار لفتح [`mjolnir-demo.mp4`](assets/video/mjolnir-demo.mp4).</sub>
+
+</details>
 
-**ما الذي حدث للتو:**
+### نتيجة واحدة عن قرب
 
-1. اكتشف Mjölnir مواصفات Playwright وإعداده وسير عمل CI وملف اختبارات
-   Python — أربع لغات/صيغ في تمريرة واحدة.
-2. وجد أدلة تُضعف الثقة في الطقم — `continue-on-error` يُخفي مهمة، و
-   `|| true` يبتلع رمز الخروج، وسبات صارم، ومحدِّد هشّ، وعناوين تجريبية
-   مضمّنة، وانتظار `networkidle`.
-3. حوّل كلًّا منها إلى اكتشاف ملموس بمعرّف قاعدة وموقع وإصلاح — وإلى
-   درجة واحدة يمكنك بوابت PR على أساسها.
+كل نتيجة تجيب عن أربعة أسئلة: أين هي، ومدى تأكد Mjölnir، وكم مرة تخطئ القاعدة، وكيف تُصلح.
 
-### اكتشاف واحد عن قرب
+<p align="center">
+  <img src="assets/readme/finding-anatomy.svg" alt="النتيجة الأولى من فحص العرض، تمامًا كما تطبعها الطرفية، مع تعليم أجزائها الأربعة: أين، ومدى التأكد، وكم مرة تخطئ القاعدة، والإصلاح." width="100%" />
+</p>
 
-شغّل `mjolnir explain QA-CI-001` على الاكتشاف الأول أعلاه وستحصل على:
+يطبع `mjolnir explain QA-CI-001` سجل الثقة الكامل لقاعدة ما، بما في ذلك معدل الإيجابيات الكاذبة المقيس لها والمستوى الذي منحها إياه هذا المعدل:
 
 ```text
-▚ QA-CI-001 — continue-on-error masks a failing verification gate
+  ▍ QA-CI-001 — continue-on-error masks a failing verification gate
 
 Severity:    error
 Confidence:  high
+Tier:        quarantine
 Evidence:    E2
-Measured FP: not yet measured — this rule ships on assumption (see docs/FP-AUDIT.md)
+QA impact:   False-green risk (FALSE-GREEN)
+Measured FP: 11% (19 hand-classified corpus verdicts)
+FP risk:     low (author estimate)
+Languages:   yaml
+Frameworks:  github-actions, azure-pipelines
 
 WHAT WAS FOUND (real detector output, not a mockup)
   Job `security-scan` runs a verification gate under `continue-on-error: true`.
 
 WHY IT MATTERS
-  This job can fail every day and CI will still show green. The checkmark
-  on this workflow cannot be trusted.
+  This job can fail every day and CI will still show green. The checkmark on
+  this workflow cannot be trusted.
 
 HOW TO FIX
   Remove continue-on-error, or scope it to individual non-blocking steps only.
-```
 
-هذه هي وحدة القيمة: ليست ملاحظة أسلوب، بل مكانٌ يقول لك فيه CI إن شيئًا
-ما قدّم — وهو لم يقدّم.
+  Example from this rule's own must-fire fixture: QA-CI-001/must-fire/masked.yml
 
----
+WHAT WOULD CHANGE THE VERDICT
+  - a run report next to the scan target (mjolnir.report.json or test-results/)
+  corroborating this file lifts its findings to L3–L5
+  - a documented suppression (mjolnir.config.json) lowers the finding count
+  without claiming correctness
+  - quarantine findings run only under --strict and are advisory (E0) — they can
+  never gate CI
 
-## ⚡ البداية السريعة
+NEXT ACTION
+  Fix the first occurrence, then re-run: `mjolnir --scope changed`. Every
+  occurrence of this rule is listed in the scan output.
 
-شغّله على مستودع للحصول على تقرير كامل ودرجة جدارة:
+HOW TO VERIFY THE FIX
+  Re-run `mjolnir` on the changed file(s) — this finding should no longer
+  appear. `mjolnir --scope changed` scopes the check to just what you touched.
 
-```bash
-npx mjolnir-qa@latest
+Docs: mjolnir rules --md   (full catalog, this rule included)
 ```
 
-**في CI، المنتج أمر واحد.** يفحص فقط ما لمسه الفرع ويخرج برمز غير صفري
-عند المشكلات الجديدة:
+هذه هي وحدة القيمة: موضع واحد يبلّغ فيه CI عن نجاح لم يستحقه.
+
+<br />
+
+## البدء السريع
 
 ```bash
-npx mjolnir-qa@latest --scope changed
+npx mjolnir-qa@latest
 ```
 
-ضعه في فحص PR — `mjolnir ci install` يكتب سير العمل — وانتهى الأمر.
-كل ما عدا ذلك اختياري.
+يفحص الدليل الحالي ويطبع Trust Report: ما الذي وجده، وإلى أي حد يمكنك الوثوق به، ولماذا، وما الخطوة التالية. ويخرج بالرمز `0` عندما لا يُعثر على شيء عند مستوى البوابة أو فوقه.
 
-| الأمر                               | ما يفعله                                             |
-| ----------------------------------- | ---------------------------------------------------- |
-| `mjolnir`                           | فحص المستودع كاملًا + درجة الجدارة                   |
-| `mjolnir --scope changed`           | ما أدخله فرعك فقط — صيغة CI                          |
-| `mjolnir ci install`                | يولّد سير عمل PR استشاريًا                           |
-| `mjolnir explain QA-CI-001`         | ماذا / لماذا / الإصلاح + معدل FP المقيس لقاعدة واحدة |
-| `mjolnir rules --unmeasured`        | القواعد العاملة بالافتراض لا بالقياس                 |
-| `mjolnir --json` / `--format sarif` | قابل للقراءة آليًا / GitHub Code Scanning            |
-| `mjolnir --strict`                  | يشغّل أيضًا قواعد طبقة الحجر الصحي (خطر FP أعلى)     |
-
-<details>
-<summary><strong>عندما يتبدّد استقرار شيء ما</strong></summary>
+في CI، افحص فقط ما أدخله الفرع، حتى لا تُغرق مجموعة اختبارات قديمة أول pull request لك:
 
-| الأمر                               | ما يفعله                                                |
-| ----------------------------------- | ------------------------------------------------------- |
-| `mjolnir forensics ./test-results/` | بيانات تشغيل حقيقية → أحكام `TRUE-FLAKE`، و`FLAKY.md`   |
-| `mjolnir triage ./test-results/`    | اقتراح حجر صحي من سجل التنفيذ                           |
-| `mjolnir pw-report ./test-results/` | ملخص تشغيل Playwright — المحاولات / المتذبذبات / الأبطأ |
-| `mjolnir doctor:playwright`         | فحص عميق لـ Playwright وحده + Selector Health Score     |
+```bash
+npx mjolnir-qa@latest --scope changed
+```
 
-</details>
+يكتب `mjolnir ci install` ذلك كـ workflow لـ GitHub Actions، باستخدام [الـ action](https://github.com/Sergey-Bar/Mjolnir#readme) المثبّت على الوسم الرئيسي `v1` (أو `npx` عادي مع `--no-action`). ويبقى استشاريًا إلى أن تقرر أنه يجب أن يمنع الدمج.
+
+| الأمر                               | ما الذي يفعله                                                |
+| ----------------------------------- | ------------------------------------------------------------ |
+| `mjolnir`                           | ‏Trust Report: الحكم، ودرجة الثقة، والإجراء التالي           |
+| `mjolnir --scope changed`           | فقط ما أدخله فرعك (صيغة CI)                                  |
+| `mjolnir ci install`                | ينشئ workflow استشاريًا لطلبات الدمج (قائمًا على الـ action) |
+| `mjolnir explain QA-CI-001`         | ماذا ولماذا وكيف يُصلح، مع معدل FP المقيس                    |
+| `mjolnir why src/a.spec.ts:42`      | لماذا عُلّم هذا السطر بالتحديد. لا يمنع الدمج أبدًا.         |
+| `mjolnir forensics ./test-results/` | أدلة وقت التشغيل من تشغيل حقيقي                              |
+| `mjolnir trust-report`              | ‏Trust Artifact مستقل (md + json)                            |
+| `mjolnir handoff`                   | خطة معالجة لوكيل برمجة                                       |
+| `mjolnir --json` / `--format sarif` | مخرجات قابلة للقراءة آليًا، GitHub Code Scanning             |
+| `mjolnir --format codequality`      | تقرير GitLab Code Quality (عنصر لأداة طلب الدمج)             |
+| `mjolnir --strict`                  | يشغّل أيضًا قواعد مستوى quarantine (خطر FP أعلى)             |
 
 <details>
-<summary><strong>عادي / تقارير</strong></summary>
-
-| الأمر                           | ما يفعله                                     |
-| ------------------------------- | -------------------------------------------- |
-| `mjolnir fix --dry-run` / `fix` | إصلاحات تلقائية آمنة مع برهان                |
-| `mjolnir baseline` / `diff`     | لقطة للاكتشافات ثم تقرير الجديد/المتدهور فقط |
-| `mjolnir impact --since <ref>`  | ما تغيّر منذ إيداع سابق                      |
-| `mjolnir debt`                  | سجل دَّين الاختبارات مع نموذج كلفة           |
-| `mjolnir handover`              | خريطة تهيئة الطقم لمسؤول جودة جديد           |
-| `mjolnir stats`                 | عدّادات محلية تراكمية للإصلاحات المرصودة     |
-| `mjolnir badge`                 | JSON لنقطة نهاية shields.io + مقطع كود       |
-| `mjolnir rules --md`            | كتالوج القواعد الكامل (JSON أو Markdown)     |
-| `mjolnir doctor`                | تدقيق ذاتي لقاعدة قواعد Mjölnir نفسها        |
-| `mjolnir create-rule <ID>`      | هيكلة قاعدة جديدة + تجهيزاتها                |
-| `mjolnir --format mermaid`      | مخطط معماري للاختبارات لتعليق PR             |
+<summary><strong>كل الأوامر الأخرى</strong> — فرز الاختبارات غير المستقرة، والتقارير، والحوكمة</summary>
+
+<br />
+
+| الأمر                               | ما الذي يفعله                                                             |
+| ----------------------------------- | ------------------------------------------------------------------------- |
+| `mjolnir --classic`                 | لافتة الدرجة السابقة لـ Trust Report                                      |
+| `mjolnir explain verdict`           | لماذا جاء حكم الفحص المحفوظ على ما هو عليه                                |
+| `mjolnir triage ./test-results/`    | فرز موجَّه. كل صف ينتهي بإجراء تالٍ.                                      |
+| `mjolnir pw-report ./test-results/` | ملخص تشغيل Playwright: إعادات المحاولة، والاختبارات غير المستقرة، والأبطأ |
+| `mjolnir doctor:playwright`         | فحص معمّق خاص بـ Playwright مع Selector Health Score                      |
+| `mjolnir fix --dry-run` / `fix`     | إصلاحات تلقائية آمنة، يُعاد فحص كل منها لإثبات أنه نجح                    |
+| `mjolnir baseline` / `diff`         | لقطة للنتائج، ثم الإبلاغ عن الجديد أو الأسوأ فقط                          |
+| `mjolnir impact --since <ref>`      | ما أدخله commit وما حلّه                                                  |
+| `mjolnir summary`                   | تعليقات CI وملخص للخطوة من تقرير                                          |
+| `mjolnir pr-comment`                | تعليق محدد النطاق على طلب الدمج، بصيغة Markdown                           |
+| `mjolnir debt`                      | سجل الدَّين التقني للاختبارات مع نموذج تكلفة                              |
+| `mjolnir handover`                  | خريطة تعريفية بمجموعة الاختبارات لمهندس QA جديد                           |
+| `mjolnir init`                      | يكتشف أُطر العمل ويطبع قائمة تحقق للإعداد                                 |
+| `mjolnir suppressions`              | يعرض النتائج المكتومة، لأغراض الحوكمة                                     |
+| `mjolnir rules --unmeasured`        | القواعد التي تعمل على افتراض، لا على قياس                                 |
+| `mjolnir rules --md`                | فهرس القواعد الكامل (JSON أو Markdown)                                    |
+| `mjolnir doctor`                    | تدقيق ذاتي لقاعدة قواعد Mjölnir نفسها                                     |
+| `mjolnir create-rule <ID>`          | ينشئ هيكلًا لقاعدة جديدة وملفات fixtures الخاصة بها                       |
+| `mjolnir stats`                     | عدّادات محلية لكل الإصلاحات التي رُصدت                                    |
+| `mjolnir badge`                     | ‏JSON لنقطة نهاية shields.io ومقتطف                                       |
+| `mjolnir --cache`                   | إعادات فحص تزايدية عبر ذاكرة تخزين مؤقت محلية للأحكام                     |
+| `mjolnir --format mermaid`          | مخطط لبنية الاختبارات لتعليق على طلب الدمج                                |
+
+يطبع `mjolnir help <command>` طريقة الاستخدام والأمثلة والخطوة التالية لأي منها.
 
 </details>
 
-ثبّته عالميًا بدل `npx` إن فضّلت: `npm i -g mjolnir-qa`.
-يتطلب Node.js ≥ 22.18. يعمل على Windows وmacOS وLinux.
-
----
-
-## 👥 لمن هذا؟
-
-- **QA / SDET** يملكون طقم e2e أو تكامل، ويحتاجون دليلًا على أن الطقم
-  يستحق فعليًا علامة النجاح الخضراء التي يُنتجها.
-- **فرق Platform / DevEx** المسؤولة عن نزاهة CI وبوابات الإصدار —
-  الأشخاص الذين يهتمون ألا يحوّل `continue-on-error` خطًّا أحمر إلى
-  أخضر بصمت.
-- **مشرفو OSS** يريدون بوابة تحقق رخيصة دائمة التشغيل تعمل محليًا وفي
-  CI دون أي نداءات شبكة.
-
----
+يتطلب **Node.js ≥ 22.18** على Windows أو macOS أو Linux. تفضّل التثبيت العام؟ `npm i -g mjolnir-qa`. يأتي هذا الحد الأدنى من سلسلة أدوات البناء (يستهدفه tsdown ويُجري خط الإصدار اختبارات دخان عليه)؛ ولا تحتاج اعتماديات وقت التشغيل أكثر من ذلك.
 
-## 🔨 ماذا يفحص Mjölnir
+<br />
 
-|     |                                                                                                                       |
-| --- | --------------------------------------------------------------------------------------------------------------------- |
-| ⚖️  | **درجة الجدارة** — رقم واحد، جدول خصم شفاف، بلا صندوق أسود                                                            |
-| 🎭  | **Selector Health Score** — يقيّم محدِّدات Playwright لديك، لا معدل نجاحك فقط                                         |
-| 🔬  | **الأدلة الجنائية للتنفيذ** — يقرأ بيانات تشغيل Playwright/JUnit الحقيقية ليلتقط `TRUE-FLAKE`، لا مجرد تخمينات ثابتة  |
-| 🚨  | **قواعد نزاهة CI** — يلتقط `continue-on-error` و`\|\| true` وحيل الأخضر الكاذب الأخرى                                 |
-| 🐍  | **ترابطات Playwright الأربعة جميعًا** — TypeScript وPython وJava وC#/.NET — إضافة إلى pytest وJUnit/TestNG وأسيرات CI |
-| 🔒  | **Local-first** — صفر نداءات شبكة أثناء الفحص، صفر قياس عن بُعد، يجري في ثوانٍ                                        |
+## ما الذي يكتشفه Mjölnir
 
-### القواعد
+<p align="center">
+  <img src="assets/readme/stack.svg" alt="يعمل مع حزمة تقنياتك: اللغات وأُطر الاختبار وأنظمة CI التي تغطيها قواعده، من سجل القواعد." width="100%" />
+</p>
 
-كل قاعدة تأتي مع تجهيزات must-fire **و**must-not-fire. القاعدة التي
-تنطلق على تجهيزتها السالبة ذاتها لا يمكن أن تُشحن — ذلك هو جدار الإنذارات
-الكاذبة.
+**79 قاعدة** في أربع عائلات — نظافة الاختبارات، وجودة الاختبارات، وPlaywright، وسلامة CI — عبر TypeScript وJavaScript وPython وJava وC# وYAML الخاص بـ GitHub Actions. تغطي Playwright في روابطه الأربعة، إضافة إلى pytest وJUnit وTestNG وNUnit وxUnit وMSTest وJest وVitest وMocha، مع تغطية مبدئية لـ Cypress وSelenium. تسع منها، لإظهار الشكل:
 
-<details>
-<summary><strong>نظافة الاختبارات</strong></summary>
-
-| ID          | القاعدة                                            | Severity |
-| ----------- | -------------------------------------------------- | -------- |
-| QA-TEST-001 | اختبار مركّز مُودَع (`.only`، `fit`)               | error    |
-| QA-TEST-002 | اختبار متجاوز بلا مسوّغ                            | error    |
-| QA-TEST-002 | اختبار متجاوز مع مسوّغ مسجَّل                      | warning  |
-| QA-TEST-003 | اختبار بلا تأكيدات                                 | error    |
-| QA-TEST-004 | سبات صارم (`waitForTimeout`، `sleep()`، `delay()`) | warning  |
-| QA-TEST-006 | إساءة استخدام المحاولات تُخفي التذبذب              | warning  |
-| QA-TEST-010 | جسد اختبار فارغ                                    | error    |
+| ID           | القاعدة                                                       | الخطورة | المستوى    |
+| ------------ | ------------------------------------------------------------- | ------- | ---------- |
+| QA-CI-001    | ‏`continue-on-error` يخفي بوابة تحقق فاشلة                    | error   | quarantine |
+| QA-CI-009    | رمز خروج الاختبارات لا يُمرَّر (`\|` دون pipefail، سلاسل `;`) | error   | extended   |
+| QA-TEST-001  | اختبار مركّز بقي في commit (`.only`، `fit`)                   | error   | quarantine |
+| QA-TEST-003  | اختبار بلا تأكيدات                                            | error   | quarantine |
+| QA-TQUAL-009 | تأكيد على promise دون await                                   | error   | quarantine |
+| QA-PW-002    | تأكيد على locator دون await                                   | error   | core       |
+| QA-PW-004    | محددات CSS/XPath هشة                                          | warning | quarantine |
+| QA-PY-002    | اختبار متخطى (`skip`، `xfail` غير صارم)                       | warning | core       |
+| QA-CS-103    | دالة اختبار بلا تأكيدات                                       | error   | core       |
 
-</details>
+يُولَّد الفهرس الكامل من السجل ولا يُصان يدويًا أبدًا: `mjolnir rules --md`، أو [`docs/rules/`](docs/rules/)، أو [دليل ما الذي يفحصه](https://sergey-bar.github.io/Mjolnir/guide/what-it-checks).
 
 <details>
-<summary><strong>جودة الاختبارات</strong></summary>
-
-| ID           | القاعدة                   | Severity |
-| ------------ | ------------------------- | -------- |
-| QA-TQUAL-002 | تأكيد مُبرهن ذاتيًا       | error    |
-| QA-TQUAL-009 | تأكيد وعد بلا await       | error    |
-| QA-TQUAL-011 | اختبارات معطَّلة بالتعليق | warning  |
+<summary><strong>كل قاعدة مذكورة في هذا الملف</strong>، في جدول واحد</summary>
+
+<br />
+
+> قواعد `quarantine` تعمل فقط مع `--strict` ولا تمنع الدمج أبدًا (إذ تُحدّ عند info). الخطورة المعروضة هي التي حددها المؤلف.
+
+| ID           | العائلة    | القاعدة                                              | الخطورة | المستوى    |
+| ------------ | ---------- | ---------------------------------------------------- | ------- | ---------- |
+| QA-TEST-001  | النظافة    | اختبار مركّز بقي في commit (`.only`، `fit`)          | error   | quarantine |
+| QA-TEST-002  | النظافة    | اختبار متخطى. يتصاعد إلى `error` دون سبب متتبَّع.    | warning | quarantine |
+| QA-TEST-003  | النظافة    | اختبار بلا تأكيدات                                   | error   | quarantine |
+| QA-TEST-004  | النظافة    | ‏sleep ثابت (`waitForTimeout`، `sleep()`، `delay()`) | warning | extended   |
+| QA-TEST-006  | النظافة    | إساءة استخدام إعادة المحاولة لإخفاء عدم الاستقرار    | warning | quarantine |
+| QA-TEST-010  | النظافة    | جسم اختبار فارغ                                      | error   | quarantine |
+| QA-TQUAL-002 | الجودة     | تأكيد تحصيل حاصل                                     | error   | quarantine |
+| QA-TQUAL-009 | الجودة     | تأكيد على promise دون await                          | error   | quarantine |
+| QA-TQUAL-011 | الجودة     | اختبارات معلّقة كتعليقات                             | warning | extended   |
+| QA-PW-002    | Playwright | تأكيد على locator دون await                          | error   | core       |
+| QA-PW-003    | Playwright | ‏`page.pause()` / `test.only()` بقيا في commit       | error   | core       |
+| QA-PW-004    | Playwright | محددات CSS/XPath هشة                                 | warning | quarantine |
+| QA-PW-123    | Playwright | عناوين URL للبيئات مثبتة في الشيفرة                  | warning | quarantine |
+| QA-PW-140    | Playwright | لقطة شاشة دون `maxDiffPixelRatio`                    | warning | core       |
+| QA-CI-001    | CI         | ‏`continue-on-error` يخفي بوابة فاشلة                | error   | quarantine |
+| QA-CI-002    | CI         | ‏`\|\| true` يبتلع رموز الخروج                       | error   | extended   |
+| QA-CI-005    | CI         | تقرير يُستهلك لكنه لا يُنشأ أبدًا                    | error   | quarantine |
+| QA-CI-007    | CI         | أغلفة إعادة المحاولة حول الاختبارات                  | warning | extended   |
+| QA-CI-008    | CI         | خطوة تنجح دائمًا تخفي الإخفاقات                      | error   | quarantine |
+| QA-CI-009    | CI         | رمز الخروج لا يُمرَّر (`\|` دون pipefail، سلاسل `;`) | error   | extended   |
+| QA-CI-010    | CI         | اختبارات متخطاة حيث يجب أن تمنع الدمج                | error   | quarantine |
+| QA-PY-002    | Python     | اختبار متخطى (`skip`، `xfail` غير صارم)              | warning | core       |
+| QA-PY-003    | Python     | دالة اختبار بلا تأكيدات                              | error   | quarantine |
+| QA-PY-005    | Python     | ‏`time.sleep()` في الاختبارات                        | warning | extended   |
+| QA-PY-012    | Python     | تأكيد تحصيل حاصل                                     | error   | quarantine |
+| QA-JV-101    | Java       | اختبار معطّل (`@Disabled`)                           | warning | core       |
+| QA-JV-102    | Java       | ‏sleep ثابت (`Thread.sleep()`)                       | warning | extended   |
+| QA-JV-103    | Java       | دالة اختبار بلا تأكيدات                              | error   | extended   |
+| QA-JV-105    | Java       | ‏sleep ثابت عبر `waitForTimeout()` في Playwright     | warning | core       |
+| QA-JV-106    | Java       | محدد هش بدل locator قائم على الدور                   | warning | quarantine |
+| QA-CS-101    | C#         | اختبار متخطى (`[Ignore]`، `[Fact(Skip=)]`)           | warning | core       |
+| QA-CS-102    | C#         | ‏sleep ثابت (`Thread.Sleep` / `Task.Delay`)          | warning | core       |
+| QA-CS-103    | C#         | دالة اختبار بلا تأكيدات                              | error   | core       |
+| QA-CS-105    | C#         | ‏sleep ثابت عبر `WaitForTimeoutAsync()`              | warning | extended   |
+| QA-CS-106    | C#         | محدد هش بدل locator قائم على الدور                   | warning | quarantine |
+
+تتضمن Python أيضًا القواعد QA-PY-001…012 (نظافة pytest) وQA-PY-101…108 (Playwright لـ Python). ولكل من Cypress وSelenium مجموعة مبدئية من ثلاث قواعد.
 
 </details>
 
-<details>
-<summary><strong>Playwright 🎭</strong></summary>
+تُطلق كل قاعدة مع ملف fixture من نوع must-fire **و**آخر من نوع must-not-fire، ولا يمكن إطلاق قاعدة تنطلق على ملف fixture السلبي الخاص بها. هذا هو جدار الحماية من الإيجابيات الكاذبة؛ ويفرضه `mjolnir doctor` في CI الخاص بهذا المستودع.
 
-| ID        | القاعدة                              | Severity |
-| --------- | ------------------------------------ | -------- |
-| QA-PW-002 | تأكيد محدِّد بلا await               | error    |
-| QA-PW-003 | `page.pause()` / `test.only()` مودعة | error    |
-| QA-PW-004 | محدِّدات CSS/XPath هشّة              | warning  |
-| QA-PW-123 | عناوين بيئات مضمّنة                  | warning  |
+### Selector Health Score
 
-</details>
+يقيّم `mjolnir doctor:playwright` كل locator حسب طريقة عثوره على العنصر: كما يفعل المستخدم (الدور، التسمية، النص)، أو عبر عقد صريح (`data-testid`)، أو بمصادفة بنيوية (سلاسل CSS، XPath). يحصل كل ملف على درجة من 0 إلى 100:
 
-<details>
-<summary><strong>نزاهة CI</strong></summary>
-
-| ID        | القاعدة                                                     | Severity |
-| --------- | ----------------------------------------------------------- | -------- |
-| QA-CI-001 | `continue-on-error` يُخفي الإخفاقات                         | error    |
-| QA-CI-002 | `\|\| true` يبتلع رموز الخروج                               | error    |
-| QA-CI-005 | تقرير يُستهلك ولا يُولَّد أبدًا                             | error    |
-| QA-CI-007 | أغلفة محاولات حول الاختبارات                                | warning  |
-| QA-CI-008 | خطوة دائمة النجاح تُخفي الإخفاقات                           | error    |
-| QA-CI-009 | رمز خروج الاختبار لا يُمرَّر (`\|` بلا pipefail، سلاسل `;`) | error    |
-| QA-CI-010 | اختبارات تُتجاوز حيث يجب أن تحجب (حرّاس skip-on-PR)         | error    |
-
-</details>
-
-<details>
-<summary><strong>Python / pytest 🐍</strong></summary>
-
-| ID        | القاعدة                                  | Severity |
-| --------- | ---------------------------------------- | -------- |
-| QA-PY-002 | اختبار متجاوز (`skip`، `xfail` غير صارم) | warning  |
-| QA-PY-003 | دالة اختبار بلا تأكيدات                  | error    |
-| QA-PY-005 | `time.sleep()` في الاختبارات             | warning  |
-| QA-PY-012 | تأكيد مُبرهن ذاتيًا                      | error    |
-
-20 قاعدة Python إجمالًا (QA-PY-001…012 نظافة pytest + QA-PY-101…108 Playwright-Python).
+```text
+  ▍ SELECTOR HEALTH
 
-</details>
+e2e/login.spec.ts
+  [█████████████░░░░░░░]  65 / 100
+  role/text: 1 · testid: 0 · plain-css: 0 · css-chains: 1 ⚠ · xpath: 0
 
-<details>
-<summary><strong>Java / JUnit · TestNG ☕</strong></summary>
+e2e/checkout.spec.ts
+  [█████████████████░░░]  86 / 100
+  role/text: 3 · testid: 1 · plain-css: 0 · css-chains: 1 ⚠ · xpath: 0
+```
 
-| ID        | القاعدة                                    | Severity |
-| --------- | ------------------------------------------ | -------- |
-| QA-JV-101 | اختبار معطَّل (`@Disabled`)                | warning  |
-| QA-JV-102 | سبات صارم (`Thread.sleep()`)               | warning  |
-| QA-JV-103 | طريقة اختبار بلا تأكيدات                   | error    |
-| QA-JV-105 | سبات صارم في Playwright `waitForTimeout()` | warning  |
-| QA-JV-106 | محدِّد هشّ بدل role locator                | warning  |
+هذا يقيس **المتانة، لا الصحة**. ينجح `.btn.btn-primary > div:nth-child(2)` اليوم ويظل ينجح إلى أن يلمس أحدٌ الترميز. الدرجة المنخفضة لا تدّعي أبدًا أن الاختبار معطوب، بل فقط أنه يعتمد على ترميز لم يعد أحد بالحفاظ عليه.
 
-</details>
+<br />
 
-<details>
-<summary><strong>C# / .NET — NUnit · xUnit · MSTest 🟣</strong></summary>
+## درجة الجدارة
 
-| ID        | القاعدة                                     | Severity |
-| --------- | ------------------------------------------- | -------- |
-| QA-CS-101 | اختبار متجاوز (`[Ignore]`، `[Fact(Skip=)]`) | warning  |
-| QA-CS-102 | سبات صارم (`Thread.Sleep` / `Task.Delay`)   | warning  |
-| QA-CS-103 | طريقة اختبار بلا تأكيدات                    | error    |
-| QA-CS-105 | سبات صارم `WaitForTimeoutAsync()`           | warning  |
-| QA-CS-106 | محدِّد هشّ بدل role locator                 | warning  |
+<p align="center">
+  <img src="assets/readme/score-gauge.svg" alt="مقياس الجدارة من 0 إلى 100، مع مؤشر يمر على كل درجة: UNWORTHY تحت 50، وNEEDS WORK من 50 إلى 79، وWORTHY من 80 إلى 99، وFORGED عند 100" width="720" />
+</p>
 
-</details>
+<sub>كل درجة من 0 إلى 100، موضوعة بواسطة `deriveScoreState` الحقيقي. مولَّد بواسطة `npm run docs:gauge` ومقفل ضد الانحراف في CI.</sub>
 
-> الكتالوج الحي الكامل — كل قاعدة بطبقتها وثقتها وخطر إنذارها الكاذب
-> وتوافر إصلاحها الآلي — يُولَّد من السجل:
->
-> ```bash
-> mjolnir rules --md
-> ```
->
-> صفحات كل قاعدة تقع تحت [`docs/rules/`](docs/rules/).
+| الدرجة    | الحكم                                       |
+| --------- | ------------------------------------------- |
+| `0 – 49`  | **UNWORTHY**                                |
+| `50 – 79` | **NEEDS WORK**                              |
+| `80 – 99` | **WORTHY**                                  |
+| `100`     | **FORGED**                                  |
+| `null`    | ‏**UNKNOWN**: لم يُعثر على تعريفات اختبارات |
 
-### كم من هذا مقيس
+**كيف تُحسب.** تحدد الخطورة خصمًا أساسيًا (`error −8`، `warning −3`، `info −1`) ويخفّضه مستوى الدليل: E2 يُحتسب كاملًا، وE1 نصفه (مقرّبًا للأسفل)، وE0 لا شيء. يُطبَّع المجموع حسب تعرّض مجموعة الاختبارات، أي الخصومات لكل تعريف اختبار لا لكل ملف. تطبع الطرفية الأرقام المخفّضة نفسها التي استخدمتها الدرجة؛ ولا يوجد نموذج ثانٍ مخفي. التفاصيل: [docs/SCORING.md](docs/SCORING.md) و[دليل الدرجة](https://sergey-bar.github.io/Mjolnir/guide/scoring).
 
-**78 من 99 قاعدة تحمل معدل إنذارات كاذبة مقيسًا على كود OSS حقيقي**
-(≥ 10 اكتشافات مصنفة يدويًا لكل منها؛ راجع
-[docs/FP-AUDIT.md](docs/FP-AUDIT.md)). الـ21 الأخرى تُشحن على تقدير
-المؤلف. ذيل كل فحص يخبرك كم من القواعد التي _انطلقت_ مقيسة؛ و
-`mjolnir rules --unmeasured` يسرد غير المقيسة؛ وصفحة `mjolnir explain`
-يدقّق عند 95% ولذلك هو في الحجر الصحي. تنمية ذلك العدد هي العمل
-المستمر للمشروع.
+**ما لا تعنيه 100.** لا تعني أن البرنامج صحيح، ولا أن مجموعة الاختبارات كافية، ولا أن المنتج خالٍ من العيوب. تعني شيئًا واحدًا: **لم تُنتج أيٌّ من القواعد التي قيّمها Mjölnir خصمًا في هذا الفحص وضمن نموذج الأدلة هذا.**
 
-### طبقات القواعد ونضج اللغات
+<br />
 
-كل قاعدة هي `core` أو `extended` أو `quarantine`، تُخصَّص وفق معدل
-إنذاراتها الكاذبة **المقيس**:
+## نموذج الأدلة
 
-| الطبقة       | المعنى                          | الفحص الافتراضي | `--strict` |
-| ------------ | ------------------------------- | :-------------: | :--------: |
-| `core`       | ≤ 10% إنذارات مقيسة             |       ✅        |     ✅     |
-| `extended`   | ≤ 30% إنذارات مقيسة             |       ✅        |     ✅     |
-| `quarantine` | فوق 30%، أو لم يقس بعد (n < 10) |       ❌        |     ✅     |
+تحمل كل نتيجة وسمين: مدى تأكد Mjölnir، وإلى أي حد جرى التحقق من النتيجة. هذا هو الفرق بين أداة تبلّغ عن أنماط وأداة يمكنك أن تربط بها قرار الإصدار.
 
-| اللغة           | المهايئ     | التغطية اليوم                                        |
-| --------------- | ----------- | ---------------------------------------------------- |
-| TypeScript / JS | AST المترجم | الأوسع والأكثر قياسًا — غالبًا `core`/`extended`     |
-| Python / pytest | طبقة regex  | واسعة، مدقَّقة على corpus — غالبًا `core`/`extended` |
-| Java            | طبقة regex  | أحدث — غالبًا `extended`/`quarantine`                |
-| C# / .NET       | طبقة regex  | أحدث — غالبًا `extended`/`quarantine`                |
+**مدى التأكد — مستوى الدليل.**
 
-TypeScript وPython يمتلكان أوسع تغطية مقيسة. Java وC# مُشحونان وموثَّقان
-وتبقيان خارج الرقم الرئيسي حتى يُدقَّق طقم مستهلك حقيقي (لا اختبارات
-مكتبة الترابط نفسها).
+| المستوى | الاسم     | المعنى                                        | الخصم |
+| ------- | --------- | --------------------------------------------- | ----- |
+| **E2**  | دليل حتمي | العيب موجود في الشيفرة كما هي مكتوبة          | كامل  |
+| **E1**  | دليل نمطي | تطابق نمط مرتبط ارتباطًا وثيقًا بالعيب        | نصف   |
+| **E0**  | ملاحظة    | تستحق المعرفة. ليست ادعاءً بأن شيئًا ما خاطئ. | صفر   |
 
----
+الثقة في الاكتشاف ليست قوة الدليل. قد تكون القاعدة متأكدة من أنها طابقت ما كانت تبحث عنه، ومع ذلك تنظر إلى استدلال تقريبي. نتائج E1 موجودة لتُقرأ ويُحكم عليها، لا لتُطبّق دون تمحيص، وهذا الحد مختوم على النتيجة في الطرفية وفي JSON وفي التسليم إلى الوكيل.
 
-## كيف يعمل التنقيط
+**إلى أي حد جرى التحقق — مستوى الثقة.** معظم النتائج تأتي من قراءة شيفرتك. أعطِ Mjölnir تقرير تشغيل اختبارات حقيقي ويمكنه أن يؤكد أن الشيفرة عملت فعلًا.
 
 <p align="center">
-  <img src="assets/readme/terminal-hero.svg" alt="ناتج الطرفية لـ Mjölnir — WORTHINESS 75/100 NEEDS WORK، تفصيل تشخيصات بحسب الفئة وقائمة FIX THIS FIRST" width="820" />
+  <img src="assets/readme/trust-ladder.svg" alt="سلّم الثقة من L0 إلى L5. تأتي L0 حتى L2 من قراءة الشيفرة؛ وتحتاج L3 حتى L5 إلى تقرير تشغيل حقيقي، ويُشار إلى ذلك بانقطاع في السلّم." width="100%" />
 </p>
 
-<sub>يُعاد توليده بـ `npm run docs:hero`؛
-[`tests/hero-asset-reproducibility.spec.ts`](tests/hero-asset-reproducibility.spec.ts)
-يُسقط CI إذا انحرفت المخرجات عمّا يطبعه المُبلِّغ فعليًا.</sub>
+| المستوى | بكلمات بسيطة     | ما الذي يتطلبه                              |
+| ------- | ---------------- | ------------------------------------------- |
+| **L0**  | مُلاحَظ          | قراءة الشيفرة                               |
+| **L1**  | يبدو أنه المشكلة | قراءة الشيفرة: تطابق نمط                    |
+| **L2**  | مُثبت في الشيفرة | قراءة الشيفرة: العيب بنيوي                  |
+| **L3**  | الملف عمل        | تقرير التشغيل يُظهر أن ملف النتيجة نُفّذ    |
+| **L4**  | الاختبار عمل     | تقرير التشغيل يُظهر أن اختبار النتيجة نُفّذ |
+| **L5**  | التشغيل يؤكد     | نتيجة التشغيل نفسها تؤكد فئة العيب          |
 
-الدرجة شفافة: **error −8، warning −3، info −1**، ثم تُطبَّع بمستوى تعرض
-الطقم (خصم لكل إعلان اختبار). الخصوم المرجَّحة بالأدلة تعني أن الإشارات
-الضعيفة أرخص. تعرض الطرفية الأرقام المخفَّضة نفسها التي تستخدمها الدرجة —
-لا صندوق أسود. المنهج الكامل: [docs/SCORING.md](docs/SCORING.md).
+يتوقف الفحص الساكن عند L2. وحده تقرير تشغيل حقيقي (Playwright JSON، أو Jest أو Vitest JSON، أو JUnit XML) يمكنه رفع نتيجة إلى L3 أو أعلى، فالنتيجة التي لم تُرَ وهي تعمل لا يمكنها أبدًا أن تدّعي أنها عملت. التعريفات: [docs/TERMINOLOGY.md](docs/TERMINOLOGY.md).
 
-**الأحكام**
+### كم من هذا مقيس
 
-| Score   | الحكم            |
-| ------- | ---------------- |
-| ≥ 80    | ✓ **WORTHY**     |
-| 50 – 79 | ⚠ **NEEDS WORK** |
-| < 50    | ✖ **UNWORTHY**   |
+**74 من أصل 79 قاعدة لديها معدل إيجابيات كاذبة مقيس على شيفرة OSS حقيقية** (10 نتائج مصنّفة يدويًا على الأقل لكل منها؛ انظر [docs/FP-AUDIT.md](docs/FP-AUDIT.md)). أما الـ 5 الأخرى فتُطلق بتقدير المؤلف وتقول ذلك، قاعدةً قاعدة، في `mjolnir explain`. يسردها `mjolnir rules --unmeasured`، ويبلّغ تذييل كل فحص عن عدد القواعد المقيسة من بين تلك التي _انطلقت_ فعلًا.
 
-**مستويات الدليل** — كل اكتشاف يحمل واحدًا؛ وهو يحدد وزن الاكتشاف في
-الدرجة:
+تبقى المعدلات علنية حتى عندما تكون سيئة. نتيجة تدقيق QA-TEST-001 (‏`.only` بقي في commit) سيئة على المستودعات الحقيقية ولذلك يقبع في quarantine. الرقم الحالي لكل قاعدة، بما فيها QA-PW-141، موجود في التدقيق.
 
-| المستوى | المعنى       | الأثر على الدرجة | مثال                                              |
-| ------- | ------------ | ---------------- | ------------------------------------------------- |
-| E2      | عيب حتمي     | خصم كامل         | `.only` مودعة — قابلة للإثبات بنيويًّا            |
-| E1      | نمط استدلالي | نصف الخصم        | `sleep()` أعادته regex — إشارة قوية، ليست برهانًا |
-| E0      | ملاحظة       | صفر (إخباري فقط) | يُبلَّغ عنه لكنه لا يبوّت CI أبدًا ولا يخصم       |
+### مستويات الثقة بالقواعد
 
-معظم القواعد **E1**. شعار «we prove it» يشير إلى هذا النظام: اكتشافات
-E2 إثبات بنيوي؛ واكتشافات E1 تحذيرات موزونة الموضع، لا براهين رسمية.
+تتبع المستويات معدل الإيجابيات الكاذبة المقيس، لا الرأي:
 
-المستودع الفارغ يحصد `null`، لا 100 مزوّرة أبدًا — انظر
-[نموذج الثقة](#نموذج-الثقة).
+| المستوى        | ‏FP المقيس                | السلوك                                                 |
+| -------------- | ------------------------- | ------------------------------------------------------ |
+| **core**       | ≤ 10%                     | التقرير الافتراضي، يمنع الدمج                          |
+| **extended**   | ≤ 30%                     | التقرير الافتراضي، ثقة أقل                             |
+| **quarantine** | > 30% أو مُعلن عنه صراحةً | مع `--strict` فقط، محدود عند info، لا يمنع الدمج أبدًا |
+| _غير مقيسة_    | n < 10                    | لا يمكن ترقيتها إلى core قبل قياسها                    |
 
----
+يمكن لأحزمة FP أن تخفض مستوى القاعدة فقط — لا تُرقى قاعدة من `quarantine` أبدًا إذا أُعلن عنها هناك صراحةً. تبقى القاعدة المُحجرة صراحةً في quarantine بغض النظر عن معدل الإيجابيات الكاذبة المقيس.
 
-## 🎭 Selector Health Score
+الترقية والتخفيض والنضج حسب اللغة: [دورة حياة القواعد](https://sergey-bar.github.io/Mjolnir/reference/rule-lifecycle).
 
-المقياس الرئيسي لأطقم Playwright — ما مدى صمود محدِّداتك:
+### لماذا هذا ليس linter
 
-```text
-▚ SELECTOR HEALTH — e2e/checkout.spec.ts
+أدوات linter تخبرك إن كانت الشيفرة تتبع القواعد. Mjölnir يخبرك إن كان يمكن الوثوق بعملية التحقق لديك.
 
-  [█████████████████░░░]  83 / 100
-  role/text: 2 · testid: 1 · css-chains: 1 ⚠ · xpath: 0
-```
+|                                                               | أدوات linter ‏(ESLint، SonarQube) | أدوات التغطية | مراجعة الشيفرة بالذكاء الاصطناعي |   **Mjölnir**    |
+| ------------------------------------------------------------- | :-------------------------------: | :-----------: | :------------------------------: | :--------------: |
+| يقيّم **نظام التحقق**، لا شيفرة المنتج                        |                لا                 |      لا       |                لا                |       نعم        |
+| سلامة ملفات workflow في CI (`continue-on-error`، `\|\| true`) |                لا                 |      لا       |            الفرق فقط             |       نعم        |
+| يقيّم متانة locators في Playwright ‏(Selector Health)         |                لا                 |      لا       |                لا                |       نعم        |
+| يقرأ بيانات تشغيل حقيقية لأحكام `TRUE-FLAKE`                  |                لا                 |      لا       |                لا                |       نعم        |
+| ينشر معدل إيجابيات كاذبة مقيسًا لكل قاعدة                     |                لا                 |      لا       |                لا                |       نعم        |
+| يعلّم الاختبارات التي بلا تأكيدات                             |               نعم\*               |      لا       |             أحيانًا              |       نعم        |
+| يلتقط sleep الثابت (`waitForTimeout`، `time.sleep`)           |               نعم\*               |      لا       |             أحيانًا              |       نعم        |
+| حتمي (المدخلات نفسها، المخرجات نفسها)                         |                نعم                |      نعم      |                لا                |       نعم        |
+| التكلفة لكل فحص                                               |               مجاني               |     مجاني     |          رموز (tokens)           | **صفر** (محليًا) |
+
+<sub>\*تغطيه `eslint-plugin-jest` و`eslint-plugin-playwright` (`expect-expect`، `no-wait-for-timeout`) وقواعد التأكيد الخاصة بـ SonarQube. تصف الأعمدة السلوك الافتراضي للتحقق من مجموعات الاختبار؛ والإضافات والخطط المدفوعة والقواعد المخصصة تغيّر بعض الإجابات. هذا ملخص تموضع، وليس اختبار أداء مقارنًا.</sub>
 
-المحدِّدات القائمة على الدور تحصد الدرجة الكاملة. سلاسل أصناف CSS وXPath
-تبطئ الدرجة — تتحطم مع أي إعادة هيكلة DOM دون إخبارك بأي سلوك ارتدّ.
+استخدم مراجعة الذكاء الاصطناعي أيضًا. فهي تلتقط الفروق الدقيقة والنية وعيوب التصميم التي لا يجدها أي نمط. ويلتقط Mjölnir ما تغفله مراجعة الذكاء الاصطناعي لأنه يبدو مقصودًا: `.only` بقي في commit، ورمز خروج مبتلع، و`continue-on-error` على job اختبار. هذه تحتاج إلى فحص، لا إلى استدلال.
 
----
+<br />
 
-## 🔬 أدلة التنفيذ
+## تحليل تشغيلات الاختبار
 
-الكشف الثابت عن التذبذب مجرد تخمين. يقرأ Mjölnir **بيانات تنفيذ حقيقية** —
-تقارير JSON من Playwright وXML من JUnit من أي مشغّل:
+التحليل الساكن يستدل على شيفرة لم تعمل قط. أما تحليل التشغيلات فيقرأ ما حدث فعلًا: Playwright JSON وJest JSON وVitest JSON وJUnit XML من أي أداة تشغيل.
 
 ```bash
 mjolnir forensics ./test-results/
 ```
 
 ```text
-▚ FLAKINESS LEADERBOARD
+  ▍ FLAKINESS LEADERBOARD
 
 3 tests · 1 failed · 1 flaky · 1 retried
 
@@ -388,275 +435,184 @@ FAILING    declines an expired card (e2e/checkout.spec.ts)
            ████░░░░░░░░░░░░░░░░ 1.1s · 1 attempt
 ```
 
-الاختبار الذي ينجح من المحاولة ≥ 2 فقط ليس اختبارًا ناجحًا — إنه اختبار
-محظوظ. يوسم `TRUE-FLAKE` بغضّ النظر عن علامة النجاح الخضراء النهائية.
+لا يعني `TRUE-FLAKE` أن الاختبار أُعيدت محاولته. بل يعني أن الاختبار **فشل في محاولة واحدة على الأقل ثم انتهى باللون الأخضر**: نجاح بالحظ، يُعلَّم مهما قالت علامة الصح النهائية. يحوّل `mjolnir triage` هذا السجل إلى اقتراح عزل، ويلخّص `mjolnir pw-report` التشغيل. وتقارير التشغيل نفسها هي ما يرفع النتائج إلى مستويات الثقة L3 فما فوق.
 
----
+<br />
 
-## ⚡ Mjölnir ليس أداة lint أخرى
+## سلامة CI
 
-أدوات lint تخبرك إن كان الكود يتبع القواعد. Mjölnir يخبرك إن كان يمكن
-الثقة بتحقّقك.
+قد ينجح اختبار بينما خط CI المحيط به لا يستطيع أن يفشل. يقرأ Mjölnir ملفات workflow أيضًا: `continue-on-error`، و`|| true`، ورموز خروج لا تُمرَّر أبدًا، وخطوات تنجح دائمًا، وتقارير تُستهلك ولا تُنشأ، وبوابات تُتخطى في الأحداث نفسها التي يجب أن تمنع الدمج. كل نتيجة تسمّي الـ job والخطوة والسطر، وتحمل مستوى دليلها الخاص.
 
-|                                                      | ESLint / SonarQube | أدوات التغطية | المراجعة اليدوية | **Mjölnir** |
-| ---------------------------------------------------- | :----------------: | :-----------: | :--------------: | :---------: |
-| نزاهة أسيرات CI (`continue-on-error`، `\|\| true`)   |         ❌         |      ❌       |      نادرًا      |     ✅      |
-| عبر اللغات (TS، Python، Java، C#) من أداة واحدة      |         ❌         |      ❌       |        ❌        |     ✅      |
-| يقيّم صمود محدِّدات Playwright (Selector Health)     |         ❌         |      ❌       |      نادرًا      |     ✅      |
-| يميّز الاختبارات بلا تأكيدات حقيقية                  |    ✅ (إضافة)\*    |      ❌       |     أحيانًا      |     ✅      |
-| يلتقط السبات الصارم (`waitForTimeout`، `time.sleep`) |    ✅ (إضافة)\*    |      ❌       |     أحيانًا      |     ✅      |
-| يجري في ثوانٍ، صفر نداءات شبكة أثناء الفحص           |         ✅         |      ✅       |        —         |     ✅      |
+أنشئ workflow طلبات الدمج، استشاريًا افتراضيًا:
 
-\*`eslint-plugin-jest` (`expect-expect`) و`eslint-plugin-playwright`
-(`expect-expect`، `no-wait-for-timeout`) يغطيان ذلك لإطاريهما.
+```bash
+mjolnir ci install
+```
 
-**التحليل التنفيذي** فئة منفصلة عن الـlint الثابت:
+أو أضف الـ action من Marketplace إلى workflow لديك بالفعل:
 
-|                                              | Playwright retry reporter | Allure / ReportPortal | **Mjölnir forensics** |
-| -------------------------------------------- | :-----------------------: | :-------------------: | :-------------------: |
-| يقرأ بيانات تشغيل حقيقية لأحكام `TRUE-FLAKE` |         جزئيًّا\*         |     جزئيًّا (tag)     |          ✅           |
-| تقرير فرز التذبذب من سجل التنفيذ             |            ❌             |          ✅           |          ✅           |
-| يتكامل مع درجة الجدارة الثابتة               |            ❌             |          ❌           |          ✅           |
+```yaml
+- uses: Sergey-Bar/Mjolnir@v1
+  with:
+    scope: changed
+    fail-on: error
+```
 
-\*Playwright يتتبع المحاولات داخليًا لكنه لا ينتج تقرير تذبذب مستقلًّا
-بملصقات أحكام.
+ثبّت `@v1` لتتبع الخط الرئيسي، أو وسمًا دقيقًا (`@v0.5.32`) لبوابة قابلة لإعادة الإنتاج. يغطي [docs/DISTRIBUTION-KIT.md](docs/DISTRIBUTION-KIT.md) كلًّا من Marketplace وSmithery وسجلات MCP.
 
----
+لوضع النتائج في GitHub Code Scanning، ارفع SARIF (يتطلب `security-events: write` على مستوى الـ workflow أو الـ job):
 
-## 🤖 لماذا لا تكتفون بمراجعة الكود بالذكاء الاصطناعي؟
+```yaml
+- run: npx mjolnir-qa@latest --format sarif > mjolnir.sarif
+  continue-on-error: true
+- uses: github/codeql-action/upload-sarif@v3
+  if: ${{ !cancelled() }}
+  with:
+    sarif_file: mjolnir.sarif
+```
 
-مشكلة مختلفة، طبقة مختلفة. المراجعة الآلية قد تلتقط تغيير اختبار مشبوهًا
-في فرق؛ لكنها لا تثبت أن نظام التحقق ككل جدير بالثقة — وهي لا ترى إلا
-الفرق الذي تريه لها.
+على GitLab، يكتب `--format codequality` تقرير Code Quality الذي تقرؤه أداة طلب الدمج وتعليقات الفرق ([docs/GITLAB-CI.md](docs/GITLAB-CI.md)). إعداد المحرر وخط CI: [docs/SARIF-INTEGRATION.md](docs/SARIF-INTEGRATION.md).
 
-|                               | مراجعة بالذكاء الاصطناعي (Copilot وغيره) |            **Mjölnir**            |
-| ----------------------------- | :--------------------------------------: | :-------------------------------: |
-| الكلفة لكل فحص                |         رموز (تتدرج بحجم الفرق)          |      **صفر** (محلي، مثبَّت)       |
-| يرى الطقم كله + كل إعدادات CI |           الفرق الذي تريه فقط            |        **كل شيء، كل مرة**         |
-| حتمي (مدخل واحد → مخرج واحد)  |              ❌ (غير حتمي)               |              **✅**               |
-| يلتقط أنماطًا راقدة أشهرًا    |          فقط إن وردت في السياق           |     **✅** (يفحص كل الملفات)      |
-| يتذكر الاكتشافات بين الجولات  |        ❌ (لا ذاكرة عبر الجلسات)         |     **✅** (baseline + diff)      |
-| يعمل دون استداء بشري          |            يحتاج PR أو موجهًا            | **✅** (خُطّاف CI، يعمل في ثوانٍ) |
+### إسناد النتائج إلى نطاق التغييرات
 
-**استخدم كليهما.** يلتقط الذكاء الاصطناعي الدقائق والقصد وعيوب التصميم
-التي لا يعثر عليها أي regex. يلتقط Mjölnir الأنماط البنيوية التي يغفلها
-الذكاء الاصطناعي لأنها تبدو «مقصودة» — `.only` مودعة، ورمز خروج مبتلع،
-و`continue-on-error` على مهمة اختبار. ليست أخطاء تحتاج تفكيرًا؛ بل حقائق
-تحتاج فحصًا.
+```bash
+npx mjolnir-qa@latest --scope changed
+```
 
----
+تُسند النتائج إلى الأسطر التي أضافها فرعك، مقيسةً مقابل **merge-base**. النطاق هو مجموعة الملفات نفسها التي يكتشفها الفحص الكامل (ملفات spec لـ TS/JS وإعدادات المحوّلات، `test_*.py`، `*Test.java`، `*Tests.cs`، `.github/workflows/*.yml`)، إضافة إلى التغييرات غير المُثبتة وغير المتتبَّعة، لذا يعمل قبل أن تُجري commit. يُحدَّد الأساس بالترتيب `main → master → origin/main → origin/master → origin/HEAD`؛ ويمكنك تجاوزه بـ `--base <ref>`.
 
-## 🤖 تكامل CI
+عندما يتعذر تحديد merge-base (نسخة ضحلة، أو HEAD منفصل، أو هدف خارج git)، تعود النتائج إلى الإسناد إلى الملف كاملًا **ويقول التقرير ذلك.** فالتراجع الصامت سيكون تمامًا نوع العيب الذي وُجدت هذه الأداة لالتقاطه.
 
-أمر واحد يولّد سير عمل PR — استشاري افتراضيًا، ولا يحجب أبدًا:
+<br />
 
-```bash
-mjolnir ci install
-```
+## وكلاء الذكاء الاصطناعي
 
-أو اربطه أصلًا في GitHub Code Scanning عبر SARIF:
+لا قيمة للنتائج إلا إذا تصرّف شيء بناءً عليها.
 
-```yaml
-- run: npx mjolnir-qa@latest --format sarif > mjolnir.sarif
-- uses: github/codeql-action/upload-sarif@v3
-  with:
-    sarif_file: mjolnir.sarif
+```text
+SCAN → EVIDENCE → HANDOFF → AGENT → RE-SCAN → PROOF
 ```
 
-إعداد المحرر والخط لـ SARIF:
-[docs/SARIF-INTEGRATION.md](docs/SARIF-INTEGRATION.md).
+**الذكاء الاصطناعي يكتب الإصلاح. Mjölnir يتحقق منه.** يأتي الدليل من إعادة الفحص، لا من تقرير الوكيل نفسه عن نجاحه.
 
-### تغطية النطاق المتغيّر
+| الأمر             | ما الذي يحصل عليه الوكيل                                                                                                                      |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mjolnir mcp`     | خادم [MCP](https://modelcontextprotocol.io) عبر stdio. تصبح `scan` و`explain` و`diff` أدوات قابلة للاستدعاء.                                  |
+| `mjolnir handoff` | يتحول تقرير `--json` محفوظ إلى خطة Markdown حتمية: ما الذي اكتُشف، وحدّ الدليل لكل نتيجة، وما الذي يجب **ألا** يتغير، وكيف يُتحقق.            |
+| `mjolnir install` | يكتب في أماكن الوكلاء الموجودة أصلًا في مستودعك (`.claude/`، `.cursor/`، `.kilo/`، `AGENTS.md`) حتى يعيد الوكيل الفحص قبل أن يدّعي أنه انتهى. |
 
-`--scope changed` يسند الاكتشافات إلى الأسطر التي أضافها فرعك مقارنة
-بنقطة دمج `main`. يغطي ملفات الاختبار (`*.spec.*`، `*.test.*`) زائد
-ملفات أسيرات GitHub وإعدادات Playwright في الفرق. عندما يتعذّر فهم
-نقطة الدمج — نسخة سطحية، HEAD منفصل، هدف بلا git، فرع افتراضي مختلف —
-يتدهور بصدق: تعود الاكتشافات إلى الإسناد بملف كامل والتقرير يقول ذلك.
-استبدل المرجع الأساس بـ `--base <ref>`.
+أضفه إلى عميل يأتي مع CLI خاص به:
 
----
-
-## الإعداد
-
-Mjölnir صفر إعداد. ملف `mjolnir.config.json` اختياري (أو `.mjolnir.json`)
-في جذر المستودع يضبط الشدة والحجب والنطاق — لا يغيّر دلالات الكشف أبدًا.
+```bash
+claude mcp add mjolnir -- npx -y mjolnir-qa@latest mcp
+```
 
-| المفتاح             | النوع                                | الأثر                                                                                                                                        |
-| ------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `exclude`           | `string[]`                           | أنماط تجاهل إضافية (مجموعة فرعية من gitignore)، فوق الافتراضيات المدمجة                                                                      |
-| `gate`              | `"advisory" \| "error" \| "warning"` | أي شدّات تخرج برمز غير صفري (الافتراضي `error`؛ `advisory` لا يحجب أبدًا)                                                                    |
-| `severityOverrides` | `{ "<RULE-ID>": severity }`          | يعيد ترتيب اكتشافات قاعدة لمستودعك                                                                                                           |
-| `ignore`            | `IgnoreEntry[]`                      | يكتم الاكتشافات — **`reason` إلزامي**؛ تنتهي صلاحية المدخلات بعد 90 يومًا (تاريخ `expires` صريح، أو زمن آخر تعديل لملف الإعداد لمن لا يذكره) |
-| `plugins`           | `string[]`                           | حزم قواعد من طرف ثالث (انظر [نموذج الثقة](#نموذج-الثقة))                                                                                     |
+أو إلى أي عميل يقبل كتلة `mcpServers`:
 
 ```json
 {
-  "gate": "error",
-  "exclude": ["legacy/**"],
-  "severityOverrides": { "QA-PW-141": "warning" },
-  "ignore": [
-    {
-      "ruleId": "QA-TEST-004",
-      "files": ["e2e/legacy-login.spec.ts"],
-      "reason": "Third-party widget needs a settle delay; tracked in JIRA-4821",
-      "expires": "2026-12-31"
-    }
-  ]
+  "mcpServers": {
+    "mjolnir": { "command": "npx", "args": ["-y", "mjolnir-qa@latest", "mcp"] }
+  }
 }
 ```
 
-- **`.mjolnirignore`** — ملف بأسلوب gitignore بسيط لاستثناء المسارات،
-  بنفس لهجة `exclude`. استخدمه للضجيج الخاص بالجهاز؛ واستخدم `exclude`
-  عندما تعود القائمة للتحكم بالإصدارات إلى جانب بقية الإعداد.
-- **تجاوزات سطر الأوامر** — `--strict` (تضمين قواعد الحجر الصحي)،
-  `--width <cols>` و`--ascii` / `--no-ascii` (عرض الطرفية)،
-  `--tone blunt` (رسائل أقسح)، `--max-duration <sec>` (فحص جزئي محدود).
-- كتم القواعد ودورة إخراجها من الخدمة:
-  [docs/RULE-LIFECYCLE.md](docs/RULE-LIFECYCLE.md).
-
-مدخلات `ignore` تُغذّي أيضًا الأمر المستقل `mjolnir suppressions` الذي
-يسرد ما هو مكتوم الآن ومتى تنتهي صلاحية كل مدخل.
-
----
-
-## 📐 رموز الخروج والعقود
-
-مجمَّدة — آمنة لبناء منطق CI فوقها:
-
-| رمز الخروج | المعنى                                                                 |
-| ---------- | ---------------------------------------------------------------------- |
-| `0`        | نظيف — لا اكتشافات عند البوابة أو فوقها                                |
-| `1`        | اكتشافات عند البوابة أو فوقها                                          |
-| `2`        | فحص جزئي (نفدت ميزانية الوقت، ملفات غير قابلة للقراءة) — لا يحجب أبدًا |
-| `10`       | خطأ استعمال (راية خاطئة، غياب هدف)                                     |
-| `20`       | خطأ داخلي                                                              |
-
-تقرير JSON/SARIF هو `schemaVersion: 1`. معرّفات القواعد
-(`QA-<FAMILY>-NNN`) لا تتغير بعد الإطلاق ولا تُعاد استخدامها أبدًا.
-
----
-
-## نموذج الثقة
-
-- **Local-first** — صفر نداءات شبكة أثناء الفحص. قطعًا. صفر قياس عن بُعد.
-- **لا برهان كاذب** — نقول «مجهول» قبل «متحقَّق منه». المستودع الفارغ
-  يأخذ `score: null`، لا 100 مزوّرة.
-- **صدق جزئي** — إذا قُطع التحليل قَصِرًا، يقول الناتج ذلك. لا «complete»
-  أبدًا حين لا يكون.
-- **جدار الإنذارات الكاذبة** — يعمل الكشف على رؤية كود خالية من
-  التعليقات/النصوص (قواعد TypeScript تستخدم AST المترجم): النمط داخل
-  تعليق نثري أو نص مثال توثيقي توثيق، لا اكتشاف.
-- **مقيس، لا مُدَّعى** — فقط القواعد ذات معدل إنذارات كاذبة من كود OSS
-  حقيقي تُشحن في الطبقات الرئيسية (انظر
-  [كم من هذا مقيس](#كم-من-هذا-مقيس))؛ ذيل الفحص و`mjolnir rules --unmeasured`
-  يخبرانك أيُّها أي.
-- **الثقة بالإضافات وبوابة التنفيذ** — الإضافات حزم npm معلنة تحت
-  `"plugins"`؛ وحدات JS تعيش في `mjolnir-rules/*.mjs`.
-  **لا غرفة رمل**: كود الإضافة يجري بكامل صلاحيات Node، النموذج نفسه
-  لإضافات ESLint أو Vitest. لهذا فإن تنفيذ الكود **اختياري في كل فحص**:
-  مرّر `--enable-plugins` (أو اضبط `MJOLNIR_ENABLE_PLUGINS=1`)، وإلا
-  فلن تُحمَّل المصادر — تنبيه صريح على stderr يسرد بالضبط ما تم تخطيه.
-  فحص كود غير موثوق لا ينفّذه أبدًا. بيانات القواعد JSON
-  (`mjolnir-rules/*.json`) غير متأثرة: تعلن أنماط regex ولا تنفذ أي
-  كود بحكم تصميمها. بادئات معرّفات القواعد الأساسية محجوزة
-  وتُرفض من الإضافات والقواعد الخارجية منعًا للانتحال.
-- **قواعد خارجية محلية للمساحة** (مجلدية، صفر شبكة) — مجلد
-  `mjolnir-rules/` بجوار هدف الفحص يحمّل قواعد مخصصة: ملفات JSON تعلن
-  أنماط regex (لا يُنفَّذ كود)، ووحدات `.mjs`/`.js` تصدّر `rules` (ثقة
-  Node كاملة، كالإضافات). القواعد الخارجية تحمل البيانات الوصفية للثقة
-  نفسها كالأساسية؛ لا يمكنها أبدًا أن تُشحن في الطبقة الأساسية (الأساسية
-  تشترط معدل إنذارات مقيسًا من ملف corpus الجانبي — التصريح بـ
-  `tier: "core"` يُقصر إلى `extended`)، وتلتزم سقوف الطبقات وتُفحص ضد
-  الانحراف: `mjolnir rules --md --external` يعرض الكتالوج من الملفات
-  المحمّلة (المصدر `external`)، ومولّد المصفوفة يقبل `--external <root>`.
-
----
-
-## 🏗️ المعمارية
+**الحاجز الواقي أهم من الراحة.** كل نتيجة في التسليم تحمل حدّها. يقول **E2** _حتمي: تحقق من الموضع وطبّق الإصلاح_. ويقول **E1** _يتطلب تأكيدًا: الملاحظة وحدها لا تثبت العيب_. الوكيل الذي يصلح E1 دون تمحيص، أو يكتم قاعدة، أو يعدّل قاعدة لرفع الدرجة، يفعل تمامًا ما وُجدت هذه الأداة لالتقاطه، ولذلك يقول التسليم ذلك في الموجِّه، بجوار النتيجة.
 
-<details>
-<summary>فصّل الشجرة</summary>
+<br />
 
-```
-mjolnir/
-├── src/
-│   ├── engine/          # LanguageAdapter interface + rule runner
-│   ├── adapters/        # typescript · python · java · csharp · github-actions
-│   ├── rules/           # rules across 8 families + the measured-FP table
-│   ├── playwright/      # Selector Health Score engine
-│   ├── discovery/       # workspace, frameworks, ignore resolution
-│   ├── scope/           # git merge-base changed-scope engine
-│   ├── scorer/          # transparent deduction table + prioritization
-│   ├── reporter/        # terminal · JSON · SARIF 2.1 · Mermaid
-│   ├── forensics/       # run-data ingestion · flake verdicts · triage
-│   ├── config/          # mjolnir.config.json + suppressions
-│   ├── plugins/         # third-party rule loading (no sandbox)
-│   └── commands/        # every subcommand
-└── tests/
-    ├── fixtures/        # must-fire / must-not-fire per rule
-    └── golden/          # frozen score regression locks
-```
+## الثقة والأمان
 
-</details>
+**محلي أولًا، بلا أي قياس عن بُعد.** لا توجد أي واجهة برمجية قادرة على الاتصال بالشبكة (`fetch`، `http`، `https`، `net`، `dns`، `dgram`، WebSocket) في أي مكان داخل `src/`، ويُفشل [`privacy-network-isolation.spec.ts`](tests/contract/privacy-network-isolation.spec.ts) عملية البناء إذا ظهرت واحدة. ويحظر أيضًا `eval` و`new Function`. فحص شيفرة غير موثوقة لا ينفّذها أبدًا: التحليل الساكن يقرأ النص المصدري، وتحليل التشغيلات يحلّل ملفات تقارير موجودة أصلًا على القرص.
+
+تحفظان: `npx` نفسه يجلب الحزمة قبل أن يعمل أي شيء، والضمان يغطي `src/` وليس إضافات الأطراف الثالثة.
+
+**الإضافات لا تعمل في بيئة معزولة.** إضافات JS (`mjolnir-rules/*.mjs`، أو حزم npm المدرجة تحت `"plugins"`) تعمل بصلاحيات Node كاملة، بنموذج الثقة نفسه الخاص بإضافات ESLint أو Vitest. تحميلها اختيار صريح **لكل فحص**: من دون `--enable-plugins` (أو `MJOLNIR_ENABLE_PLUGINS=1`) لا تُحمَّل مصادرها أبدًا، ويسرد إشعار على stderr ما جرى تخطيه. ملفات تعريف القواعد بصيغة JSON لا تنفّذ أي شيفرة، وبادئات معرّفات قواعد core محجوزة حتى لا تنتحل إضافةٌ صفة إحداها. أبلغ عن الثغرات عبر [SECURITY.md](SECURITY.md).
+
+**يعمل على نفسه.** لا مصداقية لمحرك ثقة في التحقق ما لم يكن هو نفسه قابلًا للتحقق. كل تشغيل لـ CI يفحص هذا المستودع بالبناء الذي أنتجه التشغيل نفسه. تفشل البوابة عند أي نتيجة بخطورة error، وكذلك عند فحص **جزئي** أو **قاعدة انهارت**، لأن فحصًا ذاتيًا مبتورًا لا يبلّغ عن شيء هو بالضبط الأخضر الزائف الذي وُجد هذا المشروع لالتقاطه. يعيد `mjolnir doctor` تدقيق قاعدة القواعد في التشغيل نفسه (جدار حماية الـ fixtures، وصدق المستويات، وسقف مستوى core)، والفحص الذي نتيجته INCONCLUSIVE يفشل تمامًا كالفحص الفاشل. ويُرفع التقريران كنواتج بناء.
+
+### رموز الخروج وعقد الآلة
 
-- **القواعد دوال نقية** — `(SourceFileContext) → Finding[]`، بلا I/O،
-  بلا متغيرات عامة. إضافة بيئة جديدة = مهايئ واحد + قواعده.
-- **TypeScript/Playwright تستخدم AST المترجم** (ts-morph). Python وJava
-  وC# تجري على طبقة regex مشتركة مع إخفاء التعليقات/النصوص.
-- طبقة AST من tree-sitter WASM لـ Java وC# موجودة وهي خطوة الدقة التالية —
-  لم تُوصَّل بعد إلى خط الفحص المتزامن.
+مجمّدة، حتى تتمكن من بناء منطق CI عليها:
 
----
+| رمز الخروج | المعنى                                                                |
+| ---------- | --------------------------------------------------------------------- |
+| `0`        | نظيف: لا نتائج عند مستوى البوابة أو فوقه                              |
+| `1`        | نتائج عند مستوى البوابة أو فوقه                                       |
+| `2`        | فحص جزئي (نفدت ميزانية الوقت، ملفات غير مقروءة). لا يمنع الدمج أبدًا. |
+| `10`       | خطأ في الاستخدام (خيار غير صالح، هدف مفقود)                           |
+| `20`       | خطأ داخلي                                                             |
 
-## 📚 الوثائق
+‏`2` مختلف عن `0` عمدًا: الفحص الذي لم يكتمل لم "يجد لا شيء". هو ببساطة لم ينتهِ من البحث.
 
-| المستند                                                | ما فيه                                    |
-| ------------------------------------------------------ | ----------------------------------------- |
-| [docs/SCORING.md](docs/SCORING.md)                     | تطبيع الدرجة + ترجيح الأدلة               |
-| [docs/FP-AUDIT.md](docs/FP-AUDIT.md)                   | معدلات الإنذارات الكاذبة المقيسة + المنهج |
-| [docs/RULE-LIFECYCLE.md](docs/RULE-LIFECYCLE.md)       | حالات القواعد، الكتم، الإخراج من الخدمة   |
-| [docs/SARIF-INTEGRATION.md](docs/SARIF-INTEGRATION.md) | ناتج SARIF + إعداد المحرر/CI              |
-| [docs/rules/](docs/rules/)                             | كتالوج مولَّد لكل قاعدة                   |
-| [CONTRIBUTING.md](CONTRIBUTING.md)                     | تجهيز التطوير + مساهَمة العمل             |
-| [CHANGELOG.md](CHANGELOG.md)                           | سجل الإصدارات                             |
-| [SECURITY.md](SECURITY.md)                             | الإبلاغ عن الثغرات                        |
+كل ما تستهلكه الآلة (نتائج أدوات MCP، و`--json`، وSARIF 2.1) يأتي من نتيجة معيارية واحدة وفق مخطط ذي إصدارات **لا يتوسع إلا بالإضافة** (`schemaVersion: 1`، `contractVersion: 1`)، فلا يضطر أي مستهلك إلى إعادة بناء المعنى من نص معروض. انظر [عقد الآلة](docs/machine-contract.md). معرّفات القواعد (`QA-<FAMILY>-NNN`) لا تتغير بعد إطلاقها ولا يُعاد استخدامها أبدًا.
 
----
+<br />
 
-## 📈 الحالة
+## ما لا يستطيع Mjölnir أن يخبرك به
 
-**v0.5.x · بيتا مفتوحة.** مخطط JSON ورموز الخروج عقود مجمَّدة. TypeScript
-وPython لهما أوسع تغطية مقيسة؛ Java وC# أحدث — اقرأهما عبر
-[جدول الطبقات](#طبقات-القواعد-ونضج-اللغات).
+- **لا يشغّل اختباراتك.** الفحص النظيف ليس مجموعة اختبارات ناجحة.
+- **لا يستطيع أن يخبرك بأن تأكيدًا ما _خاطئ_.** يبدو `expect(total).toBe(41)` سليمًا. يجد Mjölnir اختبارات _لا يمكن أن تفشل_ وخطوط CI _لا يمكن أن تتحول إلى الأحمر_، لا الاختبارات التي تتحقق من الشيء الخطأ.
+- **لا يثبت صحة منطق العمل.** لا شيء هنا يقول إن منتجك يفعل ما طلبته المتطلبات.
+- **الـ 100 ليست دليلًا على مجموعة اختبارات جيدة.** أما إن كانت مجموعتك تغطي مخاطرك الحقيقية فذلك سؤال مختلف، وهذه الأداة لا تجيب عنه.
+- **5 من أصل 79 قاعدة تُطلق بناءً على تقدير**، لا على معدل مقيس. وكل واحدة منها تقول ذلك في نتيجتها.
+- **E1 ليس E2.** النتائج الاستدلالية تستحق القراءة، لا التطبيق دون تمحيص.
+- **المستودع الفارغ يحصل على `null`، لا على 100 أبدًا.**
+- **الملف المسمى `*.spec.ts` الذي لا يحتوي تعريفات اختبارات لا يُحتسب تغطية.** المستودع الذي لا تحتوي ملفات spec الوحيدة فيه إلا على imports أو أنواع (صفر استدعاءات `it`/`test`) يحصل على `null`، لا على 100.
 
----
+<br />
 
-## 🤝 المساهمة
+## التوثيق
 
-القواعد الجديدة أسهل مساهمة أولى — أمر واحد يهيكل القاعدة مع تجهيزاتها
-must-fire **و**must-not-fire (القاعدة المولَّدة تفشل في تجهيزاتها عمدًا
-حتى تنفّذ كشفًا حقيقيًا — الهيكل الفارغ لا يُشحن):
+موقع التوثيق الكامل متاح على <https://sergey-bar.github.io/Mjolnir/>.
+
+| المستند                                                | ما الذي يحتويه                                         |
+| ------------------------------------------------------ | ------------------------------------------------------ |
+| [docs/SCORING.md](docs/SCORING.md)                     | تطبيع الدرجة وترجيح الأدلة                             |
+| [docs/TERMINOLOGY.md](docs/TERMINOLOGY.md)             | المفردات المعيارية: كلمة واحدة لكل مفهوم               |
+| [docs/FP-AUDIT.md](docs/FP-AUDIT.md)                   | معدلات الإيجابيات الكاذبة المقيسة والمنهجية            |
+| [docs/RULE-LIFECYCLE.md](docs/RULE-LIFECYCLE.md)       | حالات القواعد، والمستويات، والكتم، والإيقاف            |
+| [docs/VERSIONING.md](docs/VERSIONING.md)               | سياسة semver، والواجهات المجمّدة، ودورة الإيقاف        |
+| [docs/machine-contract.md](docs/machine-contract.md)   | النتيجة المعيارية القابلة للقراءة آليًا                |
+| [docs/SARIF-INTEGRATION.md](docs/SARIF-INTEGRATION.md) | مخرجات SARIF وإعداد المحرر أو CI                       |
+| [docs/GITLAB-CI.md](docs/GITLAB-CI.md)                 | ‏GitLab: تقرير Code Quality، ووصفة طلب الدمج، والبوابة |
+| [docs/rules/](docs/rules/)                             | فهرس مولَّد لكل قاعدة                                  |
+| [CONTRIBUTING.md](CONTRIBUTING.md)                     | إعداد بيئة التطوير وسير عمل المساهمة                   |
+| [SUPPORT.md](SUPPORT.md)                               | أين تسأل وتبلّغ وتحصل على المساعدة                     |
+| [SECURITY.md](SECURITY.md)                             | الإبلاغ عن الثغرات                                     |
+| [CHANGELOG.md](CHANGELOG.md)                           | سجل الإصدارات                                          |
+
+### الحالة
+
+**الإصدار 1.** مخطط JSON ورموز الخروج عقود مجمّدة. تمتلك TypeScript وPython أوسع تغطية مقيسة. أما Java وC# فأحدث؛ اقرأهما من خلال [جدول النضج](https://sergey-bar.github.io/Mjolnir/reference/rule-lifecycle). ما الذي سيأتي لاحقًا، دون تواريخ مختلقة: [خارطة الطريق العامة](https://sergey-bar.github.io/Mjolnir/reference/roadmap).
+
+### المساهمة
+
+القواعد الجديدة هي أسهل مساهمة أولى. أمر واحد ينشئ هيكل القاعدة مع ملفات fixtures من نوع must-fire **و**must-not-fire. تفشل القاعدة المولَّدة في ملفات fixtures الخاصة بها عمدًا إلى أن يُكتب اكتشاف حقيقي، لأن الهيكل الفارغ الذي يُطلق هو قاعدة لم يقسها أحد:
 
 ```bash
 mjolnir create-rule QA-PW-140 --title "Screenshot without diff bound"
 ```
 
-التجهيز التطويري الكامل، وأوامر البوابة الدائمة، وقوانين منع التوسع /
-جدار التجهيزات في [CONTRIBUTING.md](CONTRIBUTING.md).
+إعداد بيئة التطوير، وأوامر البوابات الدائمة، وقانونا anti-creep وجدار حماية الـ fixtures موجودة في [CONTRIBUTING.md](CONTRIBUTING.md).
 
----
+<br />
 
 <div align="center">
 
-**كفّوا عن شحن اختبارات لا تثقون بها.**
+<img src="assets/readme/closing.svg" alt="شغّله على مستودعك." width="100%" />
 
 ```bash
 npx mjolnir-qa@latest
 ```
 
-**Star ⭐ · Watch 👀 · Contribute 🤝**
+[اقرأ الدليل](https://sergey-bar.github.io/Mjolnir/guide/getting-started) · [موقع التوثيق](https://sergey-bar.github.io/Mjolnir/) · [npm](https://www.npmjs.com/package/mjolnir-qa)
+
+<br />
+
+لا تسأل إن كانت الاختبارات قد نجحت.<br />
+اسأل إن كانت الأدلة تثبت أنها تستحق الثقة.
 
-بُني على يد [Sergey Bar](https://www.linkedin.com/in/sergeybar/)
+<sub>من تطوير [Sergey Bar](https://www.linkedin.com/in/sergeybar/) · برخصة MIT</sub>
 
 </div>