docs: add source evidence to human review sheet

SovereignAI-Starter/ROADMAP.md

@@ -149,7 +149,7 @@
 - [x] قياس إضافي على 9 أسئلة عن ملفات الكود الفعلية (`workspace.py`, `knowledge.py`, `pdf_documents.py`, `main.py`). كشف التقييم أن تكرار مقاطع الملف الواحد يزاحم مصادر أخرى؛ حدّثنا البحث لجلب مجموعة أوسع ثم توزيع حتى مقطعين لكل ملف. بعد التعديل: Hit@1=0.667، Hit@3=1.0، MRR=0.833، وظهور الدليل=1.0. النتائج في `retrieval_2026-10-02_141132.json` (قبل التعديل) و`retrieval_2026-10-02_141337.json` (بعده). العينة صغيرة واختبارها معجمي؛ الدقة الدلالية وجودة الإجابة لم تُقاسا.
 - [x] جولة تحسين استرجاع المقاطع العميقة على 11 سؤالًا من المجموعة المحلية (2026-10-03): توسيع محدود لمرادفات صلاحيات المهارات بالعربية والإنجليزية، ورفع سقف النتائج من 5 إلى 8 مع إبقاء حد 4 مقاطع لكل ملف لحماية تنوع المصادر. على API محلي تجريبي بقاعدة معزولة: `Hit@1=1.0`, `Hit@3=1.0`, `MRR=1.0`, وظهور الدليل `11/11`؛ تقرير `evals/results/retrieval_2026-10-03_160000.json`. اجتازت اختبارات قاعدة المعرفة `12/12`.
 - [x] توسيع الحزمة وإضافة جواب الوكيل من الأدلة المفهرسة (2026-10-03): أضيف دليل تقني بطول 15.7 كيلوبايت فيه المعلومة المستهدفة في المقطع 17 وPDF نصي؛ حفظ المشغّل اختياريًا إجابات الوكيل ومصادرها للمراجعة دون منح درجة آلية. الجولة الأولى على 13 حالة أعادت `Hit@1=1.0`, `Hit@3=1.0`, `MRR=1.0`, وظهور الدليل `13/13` (`evals/results/retrieval_extended_2026-10-03.json`). بعد إصلاح وزن OCR المحلي المعطوب وإعادة تشغيله دون تنزيل، أضيف PDF ممسوح فعلي إلى المجموعة؛ على API التطبيق الحالي بقاعدة SQLite الحية المؤقتة ثم حذف عناصرها بعد القياس: `Hit@1=1.0`, `Hit@3=1.0`, `MRR=1.0`, وظهور الدليل `14/14` (`evals/results/retrieval_extended_14_2026-10-03.json`). جواب الوكيل على PDF الممسوح استخرج الموعد `17 October 2026` وذكر مصدره (`evals/results/retrieval_scanned_pdf_agent_2026-10-03.json`). تجربة EasyOCR المباشرة والـAPI استخدمتا أوزانًا محلية فقط؛ النسخة التالفة محفوظة احتياطيًا بجانب الوزن المُصلح.
-- [ ] متابعة التقييم على ملفات طويلة وPDFات متنوعة وأسئلة جديدة، وجمع مراجعة مستقلة لجودة إجابات النموذج فوق السياق المسترجع. النتائج الحالية fixtures صغيرة ومصطنعة؛ الدرجات تصف هذه الحالات ولا تثبت جودة عامة. في 2026-10-04 جُمعت 14 إجابة محفوظة من المجموعة ذات 11 حالة ومجموعتي PDF الطويل/الممسوح في ورقة مراجعة `evals/HUMAN_REVIEW_2026-10.md` مع سلم موحد وخانات فارغة؛ لا توجد درجات بشرية بعد، فلا تُحسب مرحلة المراجعة مكتملة.
+- [ ] متابعة التقييم على ملفات طويلة وPDFات متنوعة وأسئلة جديدة، وجمع مراجعة مستقلة لجودة إجابات النموذج فوق السياق المسترجع. النتائج الحالية fixtures صغيرة ومصطنعة؛ الدرجات تصف هذه الحالات ولا تثبت جودة عامة. في 2026-10-04 جُمعت 14 إجابة محفوظة من المجموعة ذات 11 حالة ومجموعتي PDF الطويل/الممسوح في ورقة مراجعة `evals/HUMAN_REVIEW_2026-10.md` مع سلم موحد وخانات فارغة. أضيفت مقتطفات المرجع بجانب كل إجابة؛ نص PDF الممسوح استُخرج محليًا بـEasyOCR (ثقة 0.591) ووسم للمراجعة مقابل الصورة الأصلية. خانات درجات البشر الأربع عشرة ما زالت فارغة؛ المراجعة لا تكتمل حتى يراجعها شخص فعليًا.
 - [x] مهارات محلية أولية قابلة للاختيار من واجهة وضع الوكيل: شرح الكود، مراجعة الكود، وخطة اختبارات. تعرض `/v1/agent/skills` وصف كل مهارة وأدواتها؛ تُحقن التعليمات الموثوقة في سياق الوكيل وتُفلتر قائمة الأدوات، ويرفض الخادم استدعاء أداة خارج صلاحيات المهارة. لمهارة مراجعة الكود معاينة فقط ولا تطبيق مباشر. اجتازت اختبارات الصلاحيات والواجهة؛ يبقى تقييم دقة كل مهارة على أمثلة أكثر قبل اعتمادها افتراضيًا.
 - [x] قراءة رابط عام محدد عبر `POST /v1/web/read`: استخراج نص HTML الثابت وتمريره إلى Gemma المحلية للإجابة مع إرجاع الرابط والعنوان.
 - [x] بحث ويب متعدد المصادر تجريبي عبر DuckDuckGo بلا مفتاح API: اختيار نطاقات مختلفة، محاولة جلب الصفحات العامة، تلخيص بالنموذج المحلي مع روابط المصادر، ووسم المقتطفات عند تعذر فتح الصفحة. (2026-10-01: استجابة حية أعادت ملخصًا ومصدرين مختلفين عبر FastAPI/Gemma.) أضيف زمن جلب إجمالي وزمن لكل مصدر إلى الاستجابة لمساعدة تشخيص المصادر البطيئة؛ اختبارات الحجب ومزوّد رسمي اختياري ما زالت لاحقًا.

SovereignAI-Starter/evals/HUMAN_REVIEW_2026-10.md

@@ -1,6 +1,6 @@
 # مراجعة بشرية لإجابات SovereignAI
 
-هذه ورقة تقييم يدوي؛ لا تُحتسب درجات الاسترجاع تلقائيًا على أنها صحة للإجابة. الحالات تأتي من مجموعات صغيرة ذات ملفات fixture للمشروع ودليل PDF طويل ومستند PDF ممسوح. راجع السؤال والإجابة والملف المشار إليه قبل تسجيل الدرجة.
+هذه ورقة تقييم يدوي؛ لا تُحتسب درجات الاسترجاع تلقائيًا على أنها صحة للإجابة. الحالات تأتي من مجموعات صغيرة ذات ملفات fixture للمشروع ودليل PDF طويل ومستند PDF ممسوح. راجع السؤال والإجابة والدليل المرجعي أدناه قبل تسجيل الدرجة. مقتطفات الحالات 1–11 هي نصوص المرجع المحددة في `knowledge_retrieval.jsonl` وليست ملفات مشروع إنتاجية. آخر حالة تعرض OCR آليًا بثقة متوسطة؛ قارنها بصورة الصفحة الأصلية.
 
 ## سلم التقييم
 
@@ -21,6 +21,10 @@
 - الملفات التي ذكرها الوكيل: storage.md, routing.md, workspace.md, images.md
 - تقرير التشغيل: `evals/results/retrieval_project_agent_fresh_api_2026-10-03.json`
 
+**الدليل المرجعي المتوقع:**
+
+> المحادثات تحفظ في قاعدة SQLite المحلية كي تبقى متاحة بعد إغلاق التطبيق أو تحديث الصفحة.
+
 **إجابة الوكيل:**
 
 > المحادثات تحفظ في قاعدة SQLite المحلية كي تبقى متاحة بعد إغلاق التطبيق أو تحديث الصفحة. (storage.md، المقطع 0)
@@ -38,6 +42,10 @@
 - الملفات التي ذكرها الوكيل: images.md, timeout.md, routing.md, pdf.md
 - تقرير التشغيل: `evals/results/retrieval_project_agent_fresh_api_2026-10-03.json`
 
+**الدليل المرجعي المتوقع:**
+
+> الصور المرفقة تحول تلقائيًا إلى نموذج Ministral 3:3b المحلي لتحليل الصورة واستخراج النص منها.
+
 **إجابة الوكيل:**
 
 > الصور المرفقة تحول تلقائيًا إلى نموذج Ministral 3:3b المحلي لتحليل الصورة واستخراج النص منها. (images.md، المقطع 0)
@@ -55,6 +63,10 @@
 - الملفات التي ذكرها الوكيل: preview.md, storage.md, pdf.md, workspace.md
 - تقرير التشغيل: `evals/results/retrieval_project_agent_fresh_api_2026-10-03.json`
 
+**الدليل المرجعي المتوقع:**
+
+> تُربط معاينة الملف ببصمة SHA256، ويجب أن يوافق المستخدم قبل تطبيق التغيير على مساحة العمل.
+
 **إجابة الوكيل:**
 
 > المقطع الذي يجيب على سؤالك هو:
@@ -73,6 +85,10 @@
 - الملفات التي ذكرها الوكيل: pdf.md, images.md, audio.md, search.md
 - تقرير التشغيل: `evals/results/retrieval_project_agent_fresh_api_2026-10-03.json`
 
+**الدليل المرجعي المتوقع:**
+
+> يستخرج pypdf النص الرقمي من صفحات PDF محليًا، ويحافظ على رقم الصفحة ضمن المقتطف المرسل للنموذج.
+
 **إجابة الوكيل:**
 
 > يستخرج `pypdf` النص الرقمي من صفحات PDF محليًا، ويحافظ على رقم الصفحة ضمن المقتطف المرسل للنموذج. (pdf.md، المقطع 0)
@@ -91,6 +107,10 @@
 - الملفات التي ذكرها الوكيل: audio.md, pdf.md, workspace.md, storage.md
 - تقرير التشغيل: `evals/results/retrieval_project_agent_fresh_api_2026-10-03.json`
 
+**الدليل المرجعي المتوقع:**
+
+> يرسل مسار الصوت التسجيل إلى Groq باستخدام Whisper للتفريغ، ثم يعود النص إلى واجهة المحادثة.
+
 **إجابة الوكيل:**
 
 > المقطع الذي يجيب على السؤال هو:
@@ -109,6 +129,10 @@
 - الملفات التي ذكرها الوكيل: workspace.md, preview.md, pdf.md, images.md
 - تقرير التشغيل: `evals/results/retrieval_project_agent_fresh_api_2026-10-03.json`
 
+**الدليل المرجعي المتوقع:**
+
+> يرفض قارئ مساحة العمل المسارات خارج الجذر، ويستثني مجلد .git والملفات المخفية وبيئات البناء.
+
 **إجابة الوكيل:**
 
 > يستطيع قارئ مساحة العمل رفض المسارات خارج الجذر، ويستثني مجلد `.git` والملفات المخفية وبيئات البناء. (workspace.md، المقطع 0)
@@ -126,6 +150,10 @@
 - الملفات التي ذكرها الوكيل: search.md, routing.md, timeout.md, images.md
 - تقرير التشغيل: `evals/results/retrieval_project_agent_fresh_api_2026-10-03.json`
 
+**الدليل المرجعي المتوقع:**
+
+> The experimental multi-source web search adapter queries DuckDuckGo and returns source URLs with the summary.
+
 **إجابة الوكيل:**
 
 > المقطع الذي يجيب على سؤالك هو:
@@ -144,6 +172,10 @@
 - الملفات التي ذكرها الوكيل: migration.md, storage.md, images.md, routing.md
 - تقرير التشغيل: `evals/results/retrieval_project_agent_fresh_api_2026-10-03.json`
 
+**الدليل المرجعي المتوقع:**
+
+> The SQLite migration adds selected_version to old messages and preserves saved assistant answer versions.
+
 **إجابة الوكيل:**
 
 > لم يتم العثور على مقطع مباشر يجيب على سؤال "How are old conversation answers migrated?" في فهرس المعرفة المحلي.
@@ -161,6 +193,10 @@
 - الملفات التي ذكرها الوكيل: routing.md, images.md, storage.md, timeout.md
 - تقرير التشغيل: `evals/results/retrieval_project_agent_fresh_api_2026-10-03.json`
 
+**الدليل المرجعي المتوقع:**
+
+> عند وصول صورة مع نموذج نصي، يختار API نموذج الرؤية المحلي المثبت ويعيد requested_model وmodel وauto_routed.
+
 **إجابة الوكيل:**
 
 > المقاطع المسترجعة من فهرس المعرفة المحلي لا تحتوي على معلومات مباشرة تحدد الحقول التي يعيدها الـ API بعد تحويل الصور بناءً على `requested_model` و`auto_routed`.
@@ -180,6 +216,10 @@
 - الملفات التي ذكرها الوكيل: routing.md, timeout.md, storage.md, search.md
 - تقرير التشغيل: `evals/results/retrieval_project_agent_fresh_api_2026-10-03.json`
 
+**الدليل المرجعي المتوقع:**
+
+> عند انتهاء مهلة النموذج المحلي، يرجع FastAPI حالة HTTP 504 مع رسالة عربية موحدة ومعرّف الطلب.
+
 **إجابة الوكيل:**
 
 > المقطع الذي يجيب على السؤال هو:
@@ -198,6 +238,10 @@
 - الملفات التي ذكرها الوكيل: skills.md, migration.md, workspace.md, preview.md
 - تقرير التشغيل: `evals/results/retrieval_project_agent_fresh_api_2026-10-03.json`
 
+**الدليل المرجعي المتوقع:**
+
+> Each local agent skill declares an allowed_tools set. The server filters the advertised tools and rejects any model call outside that set.
+
 **إجابة الوكيل:**
 
 > "Each local agent skill declares an allowed_tools set. The server filters the advertised tools and rejects any model call outside that set." (skills.md، المقطع 0)
@@ -215,6 +259,10 @@
 - الملفات التي ذكرها الوكيل: long_technical_guide.md, archive_retention_policy.pdf
 - تقرير التشغيل: `evals/results/retrieval_long_pdf_agent_2026-10-03.json`
 
+**الدليل المرجعي المتوقع — long_technical_guide.md، Release approval policy:**
+
+> A change to the production workspace requires a two-stage approval: first the user reviews the complete proposed diff, then the server verifies the original file hash and receives explicit confirmation before writing. A model-generated answer or tool call alone cannot satisfy either approval stage.
+
 **إجابة الوكيل:**
 
 > للحفظ أي تغيير مقترح في مساحة العمل، يجب أن تحدث مراجعة من مرحلتين: أولاً، يقوم المستخدم بمراجعة الفرق المقترح بالكامل، ثم يتحقق الخادم من تجزئة الملف الأصلية ويتلقى تأكيدًا صريحًا قبل الكتابة. لا يمكن لأي إجابة من النموذج أو استدعاء الأداة وحده أن يحقق مرحلة المراجعة.
@@ -234,6 +282,10 @@
 - الملفات التي ذكرها الوكيل: archive_retention_policy.pdf, long_technical_guide.md
 - تقرير التشغيل: `evals/results/retrieval_long_pdf_agent_2026-10-03.json`
 
+**الدليل المرجعي المتوقع — archive_retention_policy.pdf:**
+
+> A single PDF may contain at most 30 pages for local indexing. Digital text is extracted locally and each excerpt keeps its page number. Scanned pages are handled separately by the configured local OCR engine.
+
 **إجابة الوكيل:**
 
 > الحد الأقصى لعدد الصفحات المقبولة عند فهرسة ملف PDF واحد هو 30 صفحة.
@@ -252,6 +304,14 @@
 - الملفات التي ذكرها الوكيل: scanned_approval_notice.pdf
 - تقرير التشغيل: `evals/results/retrieval_scanned_pdf_agent_2026-10-03.json`
 
+**نص OCR المرجعي — الصفحة 1، ثقة EasyOCR المتوسطة 0.591 (تحقق من الصورة الأصلية):**
+
+> ARCHIVE RESTORATION NOTICE
+> The restoration review is complete
+> The records remain stored on the local device
+> Final approval must be recorded by an operator
+> Approval deadline: 17 October 2026
+
 **إجابة الوكيل:**
 
 > تنتهي فترة موافقة استعادة الأرشيف في 17 أكتوبر 2026. (scanned_approval_notice.pdf · المقطع 0)