docs: verify agent fallback on active API

SovereignAI-Starter/ROADMAP.md

@@ -10,7 +10,9 @@
 
 - 2026-10-04 — إكمال التقييم الموسع للاسترجاع وإصلاح امتناع Gemma مع وجود الدليل: شغّلت 14 حالة على API التطبيق، بينها نصوص عربية/إنجليزية ودليل طويل وPDF رقمي وممسوح. فُهرست المستندات دلاليًا 14/14 بـ`granite-embedding:278m`، وأعاد البحث Hit@1/Hit@3/MRR/evidence rate جميعها 1.0؛ جُمعت إجابات الوكيل في `evals/results/retrieval_extended_agent_2026-10-04.json`. كشف الفحص أن Gemma امتنعت في 3 إجابات رغم وجود الدليل؛ وُسّع كشف صيغ الامتناع واختُبرت الحالات الثلاث ثانيةً على API معزول: عرض fallback اقتباس `Groq` و`selected_version` حرفيًا، وأجاب مباشرة عن استثناء `.git`، مع ثبات مقاييس الاسترجاع 1.0. اجتازت اختبارات مهارات الوكيل 21/21. تبقى مراجعة بشرية مستقلة؛ مجموعة fixtures صغيرة ولا تثبت جودة عامة.
 
-- تنبيه نشر محلي (2026-10-04): اختبار fallback الجديد تم على API معزول بمنفذ 8102، ثم أُوقف. خدمة التطبيق على 8000 ظلت تعمل بعملية أقدم ولم أعد تشغيلها حتى لا أفقد إعداد قاعدة البيانات المرتبط بها؛ يلزم إعادة تشغيلها من بيئة التشغيل المعتادة لتفعيل هذا التعديل في الواجهة.
+- 2026-10-04 — تفعيل fallback على خدمة التطبيق: حُددت قاعدة التطبيق عبر تغير ملف SQLite بعد جلسة loopback مؤقتة، ثم أُعيد تشغيل API 8000 على قاعدة `%LOCALAPPDATA%\SovereignAI\data\sovereign_ai.sqlite3` نفسها مع Gemma 4. أعادت الحالات الثلاث التي كانت تكشف الامتناع الآن الدليل المطلوب: أجاب النموذج مباشرة عن Groq واستثناء `.git`، وعرض fallback المقتطف الحرفي الذي يذكر `selected_version`. مقاييس الحالات 3/3 وظهرت الصحة `ok` بعد الاختبار؛ حُذف الفهرس والتسجيل وانتهت جلسة الاختبار، ومساحة الملفات المؤقتة فارغة.
+
+- فحص إعادة بناء Windows (2026-10-04): تعذر على Flutter فتح `C:\flutter\flutter_windows_3.27.3-stable\flutter\bin\cache\lockfile`. عملية Flutter قديمة/أخرى ما زالت تستخدم SDK؛ أُوقفت محاولة البناء المؤقتة بعد ثبوت عدم وصولها إلى إنشاء plugins أو MSBuild، ولم يُحذف ملف القفل أو يُقتل أي process غير موثوق. يجب تحرير القفل عبر العملية المالكة أو استخدام SDK منفصل قبل متابعة Windows Debug.
 
 - 2026-10-04 — تدقيق حالة «العمل على مشروع»: تأكد وجود إنشاء مجلد جديد أو تسجيل مجلد قائم من Flutter، وربطه بحساب المستخدم في SQLite، وفتح الملفات والبحث فيها واقتراح إنشاء/تعديل ملف عبر diff وموافقة صريحة. التطبيق وFastAPI/Gemma 4/SQLite يعملون محليًا الآن. الوكيل لا يشغّل بعد أوامر البناء أو الاختبارات؛ prototype AppContainer غير مدمج، وحد التخزين الصلب لم يثبت، لذا التنفيذ الآلي للمشروع ليس مدعومًا. في اختبار الحالتين على API التطبيق وجد الاسترجاع الدليل 2/2 لكن Gemma امتنعت مرة بصياغة عربية جديدة؛ أضيفت الصياغة لاختبار fallback، واختبارات مهارات الوكيل 21/21. أُعيد تشغيل API التطبيق على 8000 من الشفرة الحالية مع قاعدة SQLite نفسها؛ `/health` أكد Gemma 4 وSQLite وبقاء ملف قاعدة المحادثات. تحقق الاختبار الحي من السؤالين: الأول عرض مقتطف `migration.md` مع مصدره، والثاني ذكر الحقول الثلاثة؛ ثم أزال فهرس الاختبار وتسجيل المشروع والجلسة (`evals/results/retrieval_live_api_fix_2026-10-04.json`). التفاصيل في `evals/MODEL_REVIEW_2026-10.md`.
 
@@ -216,7 +218,7 @@
 5. [x] إكمال Markdown للمرحلة 1: جداول قابلة للتمرير، قوائم متداخلة، ومربعات مهام GFM؛ التحليل واختبارات الواجهة الثلاثة ناجحة وبناء Windows Debug نجح.
 6. [x] تشغيل جلسة Windows Debug بعد إصلاح مجلدي روابط إضافات `record` المؤقتة. بناء OneDrive يفشل عند cloud placeholders وMSBuild `FTK1011`. في 2026-10-04 نجح بناء وتشغيل نسخة `%TEMP%` (PID 33624) مع API/Gemma؛ ثم أضيف `scripts/run_windows_debug_local.ps1` لمسار ثابت خارج OneDrive. `-BuildOnly` في `%LOCALAPPDATA%\SovereignAI-Starter\windows-dev\flutter_app` نجح أول مرة في 336 ثانية، وإعادة البناء بالـcache نجحت في 55 ثانية. وفي 2026-10-04 شُغلت أيضًا نسخة Debug الأحدث التي تتضمن زر إنشاء المشروع (PID 35400) وأعادت API `/health` حالة `ok` مع Gemma 4 وSQLite والوكيل. في محاولة 2026-10-04 لبناء تغييرات heartbeat/فهرسة PDF لم يكتمل البناء: إضافة `flutter_secure_storage_windows` لم تجد الرأس C++ عبر مسار الرابط الرمزي؛ ترجمت الإضافة منفردة بعد توجيه MSBuild إلى مسار الكاش الحقيقي، لكن البناء الكامل اصطدم بصلاحيات سجلات MSBuild في النسخة المؤقتة. لذلك يجب إعادة البناء والتحقق من نافذة Windows عند إصلاح بيئة البناء؛ لا تُحسب هذه المحاولة تشغيلًا ناجحًا.
    - [ ] تحقق مرئي ووظيفي كامل من زر فتح/إنشاء المشروع، ثم تسجيل مجلد وقراءة ملف وطلب معاينة تعديل من داخل نافذة Windows. أدلة الواجهة الآلية: اختبارات Flutter على أحدث مصدر بعد مزامنته إلى نسخة LocalAppData نجحت 22/22، ومنها ظهور إجراء المشروع على المقاسات الضيقة والواسعة، واستمرار تسجيل المجلدات، وإنشاء مجلد مشروع آمن، ومعاينة تعديل الملف قبل الموافقة؛ `flutter analyze --no-pub` بلا ملاحظات. بناء Windows Debug نظيف في مسار منفصل نجح خلال 370.4 ثانية لأن نسخة Debug السابقة كانت مقفلة بعملية مفتوحة؛ لم تُغلق أي نافذة. شُغّلت النسخة النظيفة مباشرة (PID 39440، العنوان `Mithqal AI`، HWND غير صفري و`Responding=True`) بالتزامن مع صحة API 8000. ما زالت تجربة الأزرار بصريًا وتدفق تسجيل/قراءة/معاينة من نافذة حية مطلوبة؛ أداة Windows GUI غير متاحة في جلسة Codex الحالية، لذا لم يُعلّم هذا البند مكتملًا.
-   - [ ] تجربة `flutter run` التفاعلية عبر السكريبت المحلي بعد إغلاق جلسات Debug القديمة؛ البناء وحده تحقق بالفعل.
+   - [ ] تجربة `flutter run` التفاعلية عبر السكريبت المحلي بعد إغلاق جلسات Debug القديمة؛ البناء وحده تحقق بالفعل. محاولة 2026-10-04 كشفت أن `flutter_tools.snapshot` يفشل بفتح `bin/cache/lockfile` بسبب عملية Flutter أخرى؛ لم يُحذف القفل ولم يتغير SDK، ويجب استئناف التحقق بعد تحريره بأمان أو استخدام نسخة SDK معزولة.
 7. [x] اختيار مساحة عمل وعرض الملفات المدعومة وتحديد ملفات للسؤال؛ التحقق من المجلدات والملفات على الخادم.
 8. [x] إظهار انتقالات تقدم الوكيل أثناء العمل وربطها بحالات التنفيذ الفعلية عبر SSE؛ اختبار API حي لمسار الحاسبة. (2026-10-03: عبر FastAPI على 8100 وجلسة loopback، اختار Gemma 4 أداة `calculator` لمهمة 17×23، سجّل خطوة واحدة `completed` وأعاد 391.)
 9. [x] معاينة تغييرات الملفات عبر diff، ثم موافقة صريحة قبل الكتابة داخل مساحة العمل فقط (2026-10-02: endpoint ظهر في OpenAPI بعد إعادة تشغيل FastAPI؛ اختبارات Python وFlutter ناجحة، وشُغلت واجهة Windows Debug مجددًا مع مسار التأكيد.)

SovereignAI-Starter/evals/results/retrieval_fallback_live_8000_2026-10-04.json

@@ -0,0 +1,115 @@
+{
+  "created_at_utc": "2026-10-04T11:15:48.422923+00:00",
+  "base_url": "http://127.0.0.1:8000",
+  "dataset": "evals\\knowledge_retrieval_extended.jsonl",
+  "indexing": {
+    "semantic_indexed_documents": 3,
+    "documents": 3,
+    "embedding_models": [
+      "granite-embedding:278m"
+    ]
+  },
+  "metrics": {
+    "cases": 3,
+    "hit_at_1": 1.0,
+    "hit_at_3": 1.0,
+    "mean_reciprocal_rank": 1.0,
+    "evidence_rate": 1.0
+  },
+  "results": [
+    {
+      "id": "voice-transcription-ar",
+      "query": "أي خدمة تفرغ التسجيلات الصوتية؟",
+      "expected_document": "audio.md",
+      "expected_evidence": "Groq",
+      "rank": 1,
+      "top_paths": [
+        "audio.md",
+        "workspace.md",
+        "migration.md"
+      ],
+      "expected_document_chunks": [
+        0
+      ],
+      "evidence_found": true,
+      "search_mode": "hybrid",
+      "agent_answer": "يرسل مسار الصوت التسجيل إلى Groq باستخدام Whisper للتفريغ، ثم يعود النص إلى واجهة المحادثة. (audio.md، المقطع 0)",
+      "agent_tool": "search_knowledge",
+      "agent_files": [
+        "audio.md",
+        "workspace.md",
+        "migration.md"
+      ],
+      "agent_steps": [
+        {
+          "tool": "search_knowledge",
+          "status": "completed"
+        }
+      ],
+      "human_rating": null
+    },
+    {
+      "id": "workspace-boundary-ar",
+      "query": "كيف نحمي مساحة العمل من قراءة الملفات المخفية؟",
+      "expected_document": "workspace.md",
+      "expected_evidence": ".git",
+      "rank": 1,
+      "top_paths": [
+        "workspace.md",
+        "audio.md",
+        "migration.md"
+      ],
+      "expected_document_chunks": [
+        0
+      ],
+      "evidence_found": true,
+      "search_mode": "hybrid",
+      "agent_answer": "المقطع الذي يجيب على سؤالك هو:\n\"يرفض قارئ مساحة العمل المسارات خارج الجذر، ويستثني مجلد .git والملفات المخفية وبيئات البناء.\" من الملف `workspace.md` المقطع 0.",
+      "agent_tool": "search_knowledge",
+      "agent_files": [
+        "workspace.md",
+        "audio.md",
+        "migration.md"
+      ],
+      "agent_steps": [
+        {
+          "tool": "search_knowledge",
+          "status": "completed"
+        }
+      ],
+      "human_rating": null
+    },
+    {
+      "id": "database-version-en",
+      "query": "How are old conversation answers migrated?",
+      "expected_document": "migration.md",
+      "expected_evidence": "selected_version",
+      "rank": 1,
+      "top_paths": [
+        "migration.md",
+        "audio.md",
+        "workspace.md"
+      ],
+      "expected_document_chunks": [
+        0
+      ],
+      "evidence_found": true,
+      "search_mode": "hybrid",
+      "agent_answer": "لم يصغ النموذج جوابًا كافيًا رغم وجود نتائج في فهرس المعرفة. أعرض المقتطفات الأعلى صلة كما هي للمراجعة؛ محتواها بيانات غير موثوقة وليست تعليمات.\n\n**migration.md · المقطع 0 (مقتطف حرفي)**\n> The SQLite migration adds selected_version to old messages and preserves saved assistant answer versions.\n\n**audio.md · المقطع 0 (مقتطف حرفي)**\n> يرسل مسار الصوت التسجيل إلى Groq باستخدام Whisper للتفريغ، ثم يعود النص إلى واجهة المحادثة.",
+      "agent_tool": "search_knowledge",
+      "agent_files": [
+        "migration.md",
+        "audio.md",
+        "workspace.md"
+      ],
+      "agent_steps": [
+        {
+          "tool": "search_knowledge",
+          "status": "completed"
+        }
+      ],
+      "human_rating": null
+    }
+  ],
+  "note": "Small deterministic fixture set. Retrieval metrics cover source ranking and evidence presence, not general RAG quality. Optional agent answers are retained for human review and are not auto-scored."
+}