Upload 11 files

app.py

@@ -35,12 +35,12 @@ import re
 import sys
 from pathlib import Path
 
-BRIDGE_VERSION = "app_stage_student_full_whiteboards_kindergarten_v4_0"
-BUILD_ID = "STUDENT_FULL_K12_WHITEBOARD_001"
+BRIDGE_VERSION = "app_stage_complete_question_bank_v5_3"
+BUILD_ID = "COMPLETE_QUESTION_BANK_K12_001"
 ROOT = Path(__file__).resolve().parent
 ORIGINAL_APP = ROOT / "app_original.py"
 PATCHED_CACHE = Path(
-    os.getenv("DIVID_PATCHED_APP_PATH", "/tmp/divid_teacher_app_stage_student_full_whiteboards_kindergarten_v4_0.py")
+    os.getenv("DIVID_PATCHED_APP_PATH", "/tmp/divid_teacher_app_stage_complete_question_bank_v5_3.py")
 )
 
 
@@ -99,6 +99,7 @@ set_math_whiteboard_task_from_dict = None
 math_whiteboard_grade_profile_text = None
 math_whiteboard_to_png_file = None
 math_whiteboard_to_json_file = None
+get_math_whiteboard_response = None
 
 try:
     from math_whiteboard_manager import (
@@ -108,6 +109,7 @@ try:
         grade_profile_text as math_whiteboard_grade_profile_text,
         whiteboard_to_png_file as math_whiteboard_to_png_file,
         whiteboard_to_json_file as math_whiteboard_to_json_file,
+        get_whiteboard_response as get_math_whiteboard_response,
     )
     MATH_WHITEBOARD_AVAILABLE = True
 except Exception as e:
@@ -209,6 +211,14 @@ def get_admin_manager():
         if not isinstance(question, dict):
             return []
 
+        item_type = str(
+            question.get("item_type")
+            or question.get("question_type")
+            or "multiple_choice"
+        ).strip().lower()
+        if item_type not in {"multiple_choice", "true_false", "operation"}:
+            return []
+
         buttons = question.get("option_buttons") or []
         if isinstance(buttons, list) and buttons:
             output = []
@@ -398,49 +408,101 @@ def _badge_math_board_from_state(app_state, current_board_value=None):
         profile = (
             str(math_whiteboard_grade_profile_text(grade))
             if math_whiteboard_grade_profile_text is not None
-            else "سبورة أنشطة الرياضيات"
+            else "أداة السؤال التفاعلية"
         )
     except Exception:
-        profile = "سبورة أنشطة الرياضيات"
-
-    skill_id = _badge_math_skill_from_state(app_state)
-    if not skill_id or set_math_whiteboard_task_from_dict is None:
-        if set_math_whiteboard_grade is not None:
-            try:
-                return (
-                    set_math_whiteboard_grade(grade, current_board_value),
-                    profile,
-                    "ابدأ الوسام لتحميل نشاط مرتبط بالمهارة.",
-                )
-            except Exception:
-                pass
-        return current_board_value or gr.skip(), profile, "لم يتم تحميل نشاط بعد."
+        profile = "أداة السؤال التفاعلية"
+
+    state = app_state.get("badge_state") or {}
+    question = state.get("current_question") or state.get("question") or {}
+    if not isinstance(question, dict) or not question:
+        questions = state.get("questions") or []
+        index = safe_int(state.get("current_index", 0), 0)
+        if isinstance(questions, list) and 0 <= index < len(questions):
+            question = questions[index] if isinstance(questions[index], dict) else {}
 
     try:
         from question_bank_manager import get_manager as get_question_bank_manager
 
-        result = get_question_bank_manager().get_whiteboard_task_for_skill(
-            skill_id=skill_id,
-            grade=grade,
-            source="badge",
-            include_answer=True,
-            seed=f"{app_state.get('identity','student')}|{skill_id}",
-        )
-        task = result.get("task") if isinstance(result, dict) else None
-        if isinstance(task, dict) and task.get("task_id"):
+        bank = get_question_bank_manager()
+        if isinstance(question, dict) and question.get("question_id"):
+            task = bank.question_to_whiteboard_task(
+                question,
+                source="badge_question",
+                include_answer=True,
+                max_attempts=1,
+                stop_on_first_confirmed_error=True,
+            )
             value = set_math_whiteboard_task_from_dict(task, current_board_value)
-            feature_title = str(
-                (result.get("whiteboard_feature") or {}).get("title_ar")
-                or task.get("math_feature_id")
-                or "نشاط رياضي"
+            item_type = str(question.get("item_type") or "multiple_choice")
+            return (
+                value,
+                profile,
+                f"تم تحميل سؤال فعلي من النوع: {item_type}. "
+                "أجب داخل الأداة واضغط تأكيد الإجابة، ثم اعتماد إجابة النشاط.",
+            )
+
+        skill_id = _badge_math_skill_from_state(app_state)
+        if skill_id:
+            result = bank.get_whiteboard_task_for_skill(
+                skill_id=skill_id,
+                grade=grade,
+                source="badge_practice",
+                include_answer=True,
+                seed=f"{app_state.get('identity','student')}|{skill_id}",
             )
-            return value, profile, f"تم تحميل: {feature_title}"
+            task = result.get("task") if isinstance(result, dict) else None
+            if isinstance(task, dict) and task.get("task_id"):
+                value = set_math_whiteboard_task_from_dict(task, current_board_value)
+                feature_title = str(
+                    (result.get("whiteboard_feature") or {}).get("title_ar")
+                    or task.get("math_feature_id")
+                    or "نشاط رياضي"
+                )
+                return value, profile, f"تم تحميل نشاط تدريب: {feature_title}"
     except Exception as e:
-        return current_board_value or gr.skip(), profile, f"تعذر تحميل نشاط المهارة: {e}"
+        return current_board_value or gr.skip(), profile, f"تعذر تحميل أداة السؤال: {e}"
 
-    return current_board_value or gr.skip(), profile, "لا يوجد نشاط منفذ لهذه المهارة بعد."
+    return current_board_value or gr.skip(), profile, "ابدأ الوسام لتحميل السؤال الفعلي."
 
 
+def ui_answer_badge_from_board(app_state, board_value):
+    if get_math_whiteboard_response is None:
+        state = app_state or {}
+        updates = _millionaire_button_updates(state)
+        board, profile, status = _badge_math_board_from_state(state, board_value)
+        return (
+            state,
+            "تعذر قراءة إجابة أداة السؤال.",
+            *updates,
+            "أداة السؤال غير متاحة.",
+            "",
+            "",
+            "",
+            board,
+            profile,
+            status,
+        )
+
+    response = get_math_whiteboard_response(board_value)
+    if not isinstance(response, dict) or not response:
+        state = app_state or {}
+        updates = _millionaire_button_updates(state)
+        board, profile, status = _badge_math_board_from_state(state, board_value)
+        return (
+            state,
+            "أجب داخل الأداة واضغط «تأكيد الإجابة» أولًا.",
+            *updates,
+            "لم يتم العثور على إجابة مؤكدة.",
+            "",
+            "",
+            "",
+            board,
+            profile,
+            status,
+        )
+    return ui_answer_badge_millionaire(app_state, response)
+
 def ui_load_next_student_math_activity(app_state, current_board_value=None):
     app_state = dict(app_state or {})
     grade = safe_int(app_state.get("grade", DEFAULT_GRADE), 1)
@@ -2547,7 +2609,8 @@ def ui_check():'''
                     lines=8,
                 )
             with gr.Row():
-                load_student_math_activity_btn = gr.Button("تحميل نشاط رياضي جديد", variant="primary")
+                submit_badge_board_answer_btn = gr.Button("اعتماد إجابة النشاط", variant="primary")
+                load_student_math_activity_btn = gr.Button("تحميل نشاط تدريب إضافي")
                 badge_apply_board_grade = gr.Button("تحديث أدوات النشاط حسب الصف")
                 badge_save_board_png = gr.Button("حفظ صورة النشاط PNG")
                 badge_save_board_json = gr.Button("حفظ ملف النشاط JSON")
@@ -2776,6 +2839,12 @@ def ui_check():'''
         [parent_message_thread],
     )
 
+    submit_badge_board_answer_btn.click(
+        ui_answer_badge_from_board,
+        [app_state, badge_whiteboard],
+        [app_state, badge_text, badge_answer_a, badge_answer_b, badge_answer_c, badge_answer_d, badge_unknown, badge_debug, lesson_text, remedial_video, remedial_task_id, badge_whiteboard, badge_wb_profile, badge_board_status],
+    )
+
     load_student_math_activity_btn.click(
         ui_load_next_student_math_activity,
         [app_state, badge_whiteboard],
@@ -2978,7 +3047,7 @@ def ui_check():'''
     lines.append("- admin_tools_hidden_until_login: `True`")
     lines.append("- correspondence_inside_authenticated_portals: `True`")
     lines.append("- remedial_video_renderer: `direct_html_gradio_file_url`")
-    lines.append("- badge_game_ui: `millionaire_four_buttons_plus_unknown`")
+    lines.append("- badge_game_ui: `dynamic_multi_type_plus_whiteboard_and_unknown`")
     lines.append("- whiteboard_integration: `student_free_board_plus_math_activity_board`")
     lines.append("- correspondence_ready: `True`")
     lines.append("- correspondence_lines: `outgoing + incoming`")
@@ -3206,7 +3275,7 @@ pre {
         'gradio_allowed_path("generated_media")',
         '"video_direct_url"',
         '[admin_out, admin_media_html]',
-        'badge_game_ui: `millionaire_four_buttons_plus_unknown`',
+        'badge_game_ui: `dynamic_multi_type_plus_whiteboard_and_unknown`',
         'whiteboard_integration: `student_free_board_plus_math_activity_board`',
         'with gr.Tab("السبورة", visible=False) as whiteboard_tab:',
     ]

badge_game_manager.py

@@ -725,13 +725,12 @@ class BadgeGameManager:
     ) -> Dict[str, Any]:
         q = dict(question) if isinstance(question, dict) else {}
         badge_id = self.normalize_badge_id(q.get("badge_id") or badge_id)
-
         prompt = str(
-            q.get("prompt")
-            or q.get("question")
-            or q.get("text")
-            or "اختر الإجابة الصحيحة."
+            q.get("prompt") or q.get("question") or q.get("text") or "أجب عن السؤال."
         ).strip()
+        item_type = str(
+            q.get("item_type") or q.get("question_type") or "multiple_choice"
+        ).strip().lower()
 
         raw_options = q.get("options") or q.get("choices") or []
         if isinstance(raw_options, dict):
@@ -739,34 +738,48 @@ class BadgeGameManager:
         if not isinstance(raw_options, list):
             raw_options = [raw_options]
 
-        answer = str(q.get("answer") or q.get("correct_answer") or "").strip()
-        if not answer and raw_options:
-            answer = str(raw_options[0])
-
-        answer_text = self._strip_choice_prefix(answer)
-        option_texts = self._ensure_four_options(prompt, raw_options, answer_text)
-
-        if shuffle_options:
-            random.shuffle(option_texts)
-
-        labeled_options, option_buttons = self._label_options(option_texts)
+        correct = q.get("correct_response", q.get("correct_answer", q.get("answer")))
+        option_texts: List[str] = []
+        labeled_options: List[str] = []
+        option_buttons: List[Dict[str, Any]] = []
+
+        # أزرار المليون تستخدم فقط للأنواع ذات الإجابة الواحدة.
+        if item_type in {"multiple_choice", "true_false"}:
+            answer_text = self._strip_choice_prefix(correct)
+            option_texts = self._unique_texts(raw_options)
+            if answer_text and self.normalize_answer(answer_text) not in {
+                self.normalize_answer(item) for item in option_texts
+            }:
+                option_texts.append(answer_text)
+            minimum = 2 if item_type == "true_false" else 4
+            if item_type == "multiple_choice":
+                option_texts = self._ensure_four_options(prompt, option_texts, answer_text)
+            else:
+                option_texts = option_texts[:2] or ["صح", "خطأ"]
+            if shuffle_options and item_type == "multiple_choice":
+                random.shuffle(option_texts)
+            labeled_options, option_buttons = self._label_options(option_texts)
+        else:
+            answer_text = correct
 
         cleaned = dict(q)
         cleaned.update(
             {
                 "question_id": str(
-                    q.get("question_id")
-                    or f"{badge_id}_{uuid.uuid4().hex[:10]}"
+                    q.get("question_id") or f"{badge_id}_{uuid.uuid4().hex[:10]}"
                 ),
                 "badge_id": badge_id,
                 "prompt": prompt,
                 "question": prompt,
                 "text": prompt,
-                "answer": answer_text,
-                "correct_answer": answer_text,
+                "item_type": item_type,
+                "question_type": item_type,
+                "answer": correct,
+                "correct_answer": correct,
+                "correct_response": correct,
                 "option_texts": option_texts,
-                "options": labeled_options,
-                "choices": labeled_options,
+                "options": labeled_options if option_buttons else raw_options,
+                "choices": labeled_options if option_buttons else raw_options,
                 "option_buttons": option_buttons,
                 "unknown_option": {
                     "id": "unknown",
@@ -776,11 +789,10 @@ class BadgeGameManager:
                     "separate": True,
                 },
                 "unknown_label": self.UNKNOWN_LABEL,
-                "game_style": "millionaire",
+                "game_style": "multi_type_mastery",
                 "answer_locked": False,
             }
         )
-
         cleaned.setdefault("subject", "math")
         cleaned.setdefault("subject_name", "رياضيات")
         cleaned.setdefault("skill_id", badge_id)
@@ -789,22 +801,35 @@ class BadgeGameManager:
         cleaned.setdefault("difficulty", 1)
         cleaned.setdefault("error_type_if_wrong", "unknown_error")
         cleaned.setdefault("explanation", "")
-
+        cleaned.setdefault("allow_dont_know", True)
+        cleaned.setdefault("confirm_before_submit", True)
         return cleaned
 
     def question_text(self, question: Dict[str, Any], index: int = 0, total: int = 0) -> str:
         prompt = str(
-            question.get("prompt")
-            or question.get("question")
-            or question.get("text")
-            or ""
+            question.get("prompt") or question.get("question") or question.get("text") or ""
         ).strip()
-
-        # لا نكرر الخيارات داخل النص؛ app.py يعرضها كأزرار مستقلة.
+        item_type = str(question.get("item_type") or "multiple_choice")
+        instruction = {
+            "multiple_choice": "اختر إجابتك من الأزرار، أو اضغط لا أعلم.",
+            "true_false": "اختر صح أو خطأ، أو اضغط لا أعلم.",
+            "multi_select": "اختر جميع الإجابات الصحيحة من أداة السؤال ثم أكّد.",
+            "numeric_input": "اكتب الإجابة الرقمية في أداة السؤال ثم أكّد.",
+            "fill_blank": "أكمل الفراغ في أداة السؤال ثم أكّد.",
+            "ordering": "رتّب العناصر في أداة السؤال ثم أكّد.",
+            "matching": "نفّذ المطابقة في أداة السؤال ثم أكّد.",
+            "drag_drop": "اسحب العناصر إلى أماكنها ثم أكّد.",
+            "short_answer": "اكتب إجابة قصيرة ثم أكّد.",
+            "oral_response": "قل الإجابة أو اكتبها عند تعذر الميكروفون.",
+            "number_line": "حدّد القيمة المطلوبة على خط الأعداد.",
+            "graph_interaction": "استخدم الرسم أو اكتب النقطة المطلوبة.",
+            "whiteboard_response": "حل أو ارسم على السبورة ثم أكّد.",
+            "interactive_game": "نفّذ النشاط التفاعلي ثم أكّد.",
+        }.get(item_type, "أجب في أداة السؤال ثم أكّد.")
         return (
             f"السؤال {index + 1} من {total}\n\n"
             f"{prompt}\n\n"
-            "اختر إجابتك من الأزرار، أو اضغط لا أعلم."
+            f"{instruction}"
         ).strip()
 
     def build_question_ui(
@@ -918,7 +943,7 @@ class BadgeGameManager:
             "skill_title": cleaned_questions[0].get("skill_title", (badge or {}).get("skill_title", "")),
             "mastery_scope": "exact_skill" if (exact_skill_id or str(badge_id).startswith("DIVID-MATH-")) else "legacy_badge",
             "status": "active",
-            "game_style": "millionaire",
+            "game_style": "multi_type_mastery",
             "assessment_mode": "exact_skill_mastery_check",
             "millionaire_ladder": self.build_ladder(0, len(cleaned_questions)),
             "current_prize": self.prize_for_index(0, len(cleaned_questions)),
@@ -997,40 +1022,39 @@ class BadgeGameManager:
         self,
         answer: Any,
         question: Dict[str, Any],
-    ) -> str:
+    ) -> Any:
+        if isinstance(answer, list):
+            return answer
         if isinstance(answer, dict):
-            answer = (
-                answer.get("value")
-                or answer.get("text")
-                or answer.get("label")
-                or answer.get("key")
-                or ""
-            )
+            # استجابة السبورة أو المطابقة تبقى كما هي للتصحيح المركزي.
+            if "answer" in answer or answer.get("type") == "dont_know":
+                return answer
+            if any(key in answer for key in ["value", "text", "label", "key"]):
+                answer = (
+                    answer.get("value")
+                    or answer.get("text")
+                    or answer.get("label")
+                    or answer.get("key")
+                    or ""
+                )
+            else:
+                return answer
 
         text = str(answer or "").strip()
         if not text:
             return ""
-
         if self.is_unknown(text):
             return self.UNKNOWN_LABEL
-
         normalized = self.normalize_answer(text)
-
         for button in question.get("option_buttons", []) or []:
             if not isinstance(button, dict):
                 continue
-
             candidates = [
-                button.get("value"),
-                button.get("text"),
-                button.get("label"),
-                button.get("key"),
-                button.get("arabic_key"),
+                button.get("value"), button.get("text"), button.get("label"),
+                button.get("key"), button.get("arabic_key"),
             ]
-
             if normalized in {self.normalize_answer(item) for item in candidates}:
                 return str(button.get("value") or button.get("text") or text)
-
         return self._strip_choice_prefix(text)
 
     def _register_error(
@@ -1178,14 +1202,28 @@ class BadgeGameManager:
                 "version": self.version,
             }
 
-        correct = str(
-            current_question.get("answer")
-            or current_question.get("correct_answer")
-            or ""
-        ).strip()
+        correct = current_question.get(
+            "correct_response",
+            current_question.get("correct_answer", current_question.get("answer")),
+        )
 
-        unknown = self.is_unknown(selected)
-        is_correct = False if unknown else self.answer_matches(selected, correct)
+        unknown = (
+            (isinstance(selected, dict) and selected.get("type") == "dont_know")
+            or (not isinstance(selected, (dict, list)) and self.is_unknown(selected))
+        )
+        scoring_result = {}
+        if unknown:
+            is_correct = False
+        else:
+            try:
+                from question_bank_manager import get_manager as get_question_bank_manager
+                scoring_result = get_question_bank_manager().score_response(
+                    current_question,
+                    selected,
+                )
+                is_correct = scoring_result.get("is_correct") is True
+            except Exception:
+                is_correct = self.answer_matches(selected, correct)
 
         if is_correct:
             answer_type = "correct"
@@ -1209,8 +1247,10 @@ class BadgeGameManager:
             "question_id": current_question.get("question_id", ""),
             "prompt": current_question.get("prompt", ""),
             "selected": selected,
-            "selected_raw": str(answer or ""),
+            "selected_raw": json.dumps(answer, ensure_ascii=False, default=str) if isinstance(answer, (dict, list)) else str(answer or ""),
             "correct": correct,
+            "item_type": current_question.get("item_type", "multiple_choice"),
+            "scoring_result": scoring_result,
             "is_correct": is_correct,
             "answer_type": answer_type,
             "diagnostic_status": answer_type,
@@ -1681,7 +1721,7 @@ class BadgeGameManager:
             "level_test_is_separate": False,
             "prize_ladder_top": 1000000,
             "question_display": "question_only_without_duplicate_options",
-            "answer_options": 4,
+            "answer_options": "dynamic_by_item_type",
             "unknown_is_separate_button": True,
             "unknown_label": self.UNKNOWN_LABEL,
             "help_trigger": {
@@ -1710,10 +1750,7 @@ class BadgeGameManager:
                 "request_help",
                 "summary",
             ],
-            "message": (
-                "BadgeGameManager جاهز بنمط المسابقات: أربعة اختيارات، "
-                "زر لا أعلم مستقل، ومساعدة بعد تكرار الخطأ."
-            ),
+            "message": "BadgeGameManager جاهز للأسئلة متعددة الأنواع مع زر لا أعلم والتوقف عند أول خطأ مؤكد.",
         }
 
 

deepmind_compatible_generator.py

@@ -0,0 +1,54 @@
+# deepmind_compatible_generator.py
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+مولد محلي متوافق مع عائلات Google DeepMind Mathematics Dataset.
+لا ينسخ كود المنبع؛ ينفذ مولدات بسيطة مستقلة ويثبت المصدر والترخيص والـ seed.
+License notice for upstream method reference: Apache-2.0.
+"""
+from __future__ import annotations
+import random
+from fractions import Fraction
+
+VERSION = "deepmind_compatible_generator_v1"
+
+def generate_linear_equation(seed: int = 0):
+    rng = random.Random(seed)
+    x = rng.randint(-20, 30)
+    a = rng.choice([n for n in range(-9, 10) if n])
+    b = rng.randint(-30, 30)
+    c = a * x + b
+    return {
+        "module": "algebra/linear_1d",
+        "seed": seed,
+        "question_ar": f"حل المعادلة: {a}س + ({b}) = {c}",
+        "correct_response": x,
+    }
+
+def generate_arithmetic(seed: int = 0):
+    rng = random.Random(seed)
+    a = rng.randint(10, 900)
+    b = rng.randint(2, 99)
+    c = rng.randint(2, 20)
+    return {
+        "module": "arithmetic/mixed",
+        "seed": seed,
+        "question_ar": f"احسب: {a} + {b} × {c}",
+        "correct_response": a + b * c,
+    }
+
+def generate_probability(seed: int = 0):
+    rng = random.Random(seed)
+    red = rng.randint(2, 8)
+    blue = rng.randint(2, 8)
+    total = red + blue
+    answer = Fraction(red * (red - 1), total * (total - 1))
+    return {
+        "module": "probability/sampling_without_replacement",
+        "seed": seed,
+        "question_ar": (
+            f"في كيس {red} كرات حمراء و{blue} زرقاء. "
+            "ما احتمال سحب كرتين حمراوين دون إرجاع؟"
+        ),
+        "correct_response": str(answer),
+    }

external_question_import_manager.py

@@ -0,0 +1,103 @@
+# external_question_import_manager.py
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+import hashlib
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+VERSION = "external_question_import_manager_v1"
+
+class ExternalQuestionImportManager:
+    def __init__(self, root_dir: Optional[str | Path] = None) -> None:
+        self.root_dir = Path(root_dir or Path(__file__).resolve().parent)
+        self.sources_path = self.root_dir / "assessment_source_registry.json"
+        self.items_path = self.root_dir / "external_assessment_items.json"
+        self.policy_path = self.root_dir / "question_import_policy.json"
+        self.reload()
+
+    def reload(self) -> Dict[str, Any]:
+        self.sources_data = json.loads(self.sources_path.read_text(encoding="utf-8"))
+        self.items_data = json.loads(self.items_path.read_text(encoding="utf-8"))
+        self.policy = json.loads(self.policy_path.read_text(encoding="utf-8"))
+        self.sources = {str(x["source_id"]): x for x in self.sources_data.get("sources", [])}
+        return self.summary()
+
+    @staticmethod
+    def _id(source_id: str, source_item_id: str, question: str) -> str:
+        digest = hashlib.sha256(f"{source_id}|{source_item_id}|{question}".encode("utf-8")).hexdigest()[:18]
+        return f"EXT-{source_id}-{digest}"
+
+    def validate_item(self, item: Dict[str, Any], commercial_mode: bool = True) -> Dict[str, Any]:
+        errors: List[str] = []
+        required = self.policy.get("required_item_fields", [])
+        for field in required:
+            if field not in item or item.get(field) in (None, ""):
+                errors.append(f"missing:{field}")
+        source_id = str(item.get("source_id") or "")
+        source = self.sources.get(source_id)
+        if not source:
+            errors.append("unknown_source_id")
+        else:
+            if commercial_mode and item.get("commercial_use_allowed") is False:
+                errors.append("noncommercial_item_in_commercial_mode")
+            license_text = str(item.get("license") or "").upper()
+            if "ND" in license_text and str(item.get("adapted_or_verbatim")) != "verbatim":
+                errors.append("no_derivatives_license_blocks_adaptation")
+            if source.get("production_action") in {"reference_alignment_only", "alignment_reference_only", "no_import_without_contract", "link_or_reference_only"}:
+                errors.append("source_not_approved_for_item_import")
+        if item.get("skill_id") in (None, ""):
+            errors.append("missing_skill_mapping")
+        if item.get("status") == "approved" and item.get("translation_status") not in {"not_needed", "human_reviewed", "approved"}:
+            errors.append("translation_not_approved")
+        return {"success": not errors, "errors": errors, "version": VERSION}
+
+    def stage_item(self, item: Dict[str, Any]) -> Dict[str, Any]:
+        record = dict(item)
+        record.setdefault("external_item_id", self._id(str(record.get("source_id")), str(record.get("source_item_id")), str(record.get("question"))))
+        record["status"] = "staging"
+        validation = self.validate_item(record, commercial_mode=False)
+        record["validation"] = validation
+        self.items_data.setdefault("staging_items", []).append(record)
+        self._save()
+        return record
+
+    def approve_item(self, external_item_id: str, commercial_mode: bool = True) -> Dict[str, Any]:
+        staging = self.items_data.get("staging_items", [])
+        for index, record in enumerate(staging):
+            if str(record.get("external_item_id")) != str(external_item_id):
+                continue
+            candidate = dict(record)
+            candidate["status"] = "approved"
+            validation = self.validate_item(candidate, commercial_mode=commercial_mode)
+            candidate["validation"] = validation
+            if not validation["success"]:
+                return {"success": False, "record": candidate, "errors": validation["errors"]}
+            self.items_data.setdefault("items", []).append(candidate)
+            staging.pop(index)
+            self._save()
+            return {"success": True, "record": candidate}
+        return {"success": False, "errors": ["item_not_found"]}
+
+    def _save(self) -> None:
+        self.items_data["approved_items_count"] = len(self.items_data.get("items", []))
+        self.items_data["staging_items_count"] = len(self.items_data.get("staging_items", []))
+        self.items_path.write_text(json.dumps(self.items_data, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    def summary(self) -> Dict[str, Any]:
+        return {
+            "version": VERSION,
+            "sources_count": len(self.sources),
+            "approved_items_count": len(self.items_data.get("items", [])),
+            "staging_items_count": len(self.items_data.get("staging_items", [])),
+        }
+
+_MANAGER: Optional[ExternalQuestionImportManager] = None
+
+def get_manager() -> ExternalQuestionImportManager:
+    global _MANAGER
+    if _MANAGER is None:
+        _MANAGER = ExternalQuestionImportManager()
+    return _MANAGER

question_bank_manager.py

@@ -15,7 +15,12 @@ from fractions import Fraction
 from pathlib import Path
 from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
 
-VERSION = "question_bank_manager_v7_student_k12_registry_runtime"
+try:
+    from question_clarification_manager import QuestionClarificationManager
+except Exception:
+    QuestionClarificationManager = None
+
+VERSION = "question_bank_manager_v11_math_concepts_clarification"
 
 
 def _read_json(path: Path) -> Dict[str, Any]:
@@ -58,6 +63,8 @@ class QuestionBankManager:
         self.whiteboard_registry_data: Dict[str, Any] = {}
         self.whiteboard_features_by_skill: Dict[str, List[str]] = {}
         self.whiteboard_feature_records: Dict[str, Dict[str, Any]] = {}
+        self.clarification_manager = None
+        self.clarification_error = ""
         self.reload()
 
     def reload(self) -> Dict[str, Any]:
@@ -96,6 +103,15 @@ class QuestionBankManager:
                     key = str(skill_id or "").strip()
                     if key:
                         self.whiteboard_features_by_skill.setdefault(key, []).append(feature_id)
+            if QuestionClarificationManager is not None:
+                try:
+                    self.clarification_manager = QuestionClarificationManager(
+                        root_dir=self.root_dir
+                    )
+                    self.clarification_error = ""
+                except Exception as exc:
+                    self.clarification_manager = None
+                    self.clarification_error = repr(exc)
             return self.summary()
 
 
@@ -914,6 +930,19 @@ class QuestionBankManager:
             "template_id":tpl.get("template_id"),
             "skill_id":skill_id,
             "skill_title":skill.get("title",{}).get("ar"),
+            "concept_ids":skill.get("concept_ids",[]),
+            "symbol_ids":skill.get("symbol_ids",[]),
+            "clarification_available":True,
+            "clarification_scored":False,
+            "clarification_is_hint":False,
+            "clarification_contract":{
+                "may_rephrase_question":True,
+                "may_explain_symbols":True,
+                "may_show_concept_aliases":True,
+                "hide_target_concept_definition":True,
+                "does_not_reduce_score":True,
+                "does_not_add_attempt":True,
+            },
             "badge_id":(skill.get("badge_ids") or [""])[0],
             "badge_ids":skill.get("badge_ids",[]),
             "grade_range":skill.get("grade_range",{}),
@@ -953,6 +982,65 @@ class QuestionBankManager:
         if not validation["success"]: result["success"]=False
         return result
 
+    def clarify_question(
+        self,
+        question: Dict[str, Any] | str,
+        assessed_concept_ids: Optional[Iterable[str]] = None,
+        assessed_symbol_ids: Optional[Iterable[str]] = None,
+        assessment_mode: bool = True,
+    ) -> Dict[str, Any]:
+        if self.clarification_manager is None:
+            return {
+                "success": False,
+                "message": "مدير توضيح السؤال غير متاح.",
+                "error": self.clarification_error,
+                "evaluation_effect": {
+                    "scored": False,
+                    "counts_as_hint": False,
+                },
+            }
+        if isinstance(question, dict):
+            question_text = str(
+                question.get("question")
+                or question.get("prompt")
+                or question.get("question_ar")
+                or ""
+            )
+            skill_id = str(question.get("skill_id") or "")
+            if assessed_concept_ids is None:
+                assessed_concept_ids = question.get("assessed_concept_ids") or []
+            if assessed_symbol_ids is None:
+                assessed_symbol_ids = question.get("assessed_symbol_ids") or []
+        else:
+            question_text = str(question or "")
+            skill_id = ""
+        return self.clarification_manager.clarify_question(
+            question_text=question_text,
+            skill_id=skill_id,
+            assessed_concept_ids=assessed_concept_ids,
+            assessed_symbol_ids=assessed_symbol_ids,
+            assessment_mode=assessment_mode,
+        )
+
+    def get_concept_dictionary_entry(self, concept_id: str) -> Dict[str, Any]:
+        if self.clarification_manager is None:
+            return {}
+        return self.clarification_manager.get_concept(concept_id)
+
+    def get_symbol_dictionary_entry(self, symbol_id: str) -> Dict[str, Any]:
+        if self.clarification_manager is None:
+            return {}
+        return self.clarification_manager.get_symbol(symbol_id)
+
+    def get_remedial_concept_package(self, skill_id: str) -> Dict[str, Any]:
+        if self.clarification_manager is None:
+            return {
+                "success": False,
+                "skill_id": skill_id,
+                "message": "قاموس المفاهيم غير متاح.",
+            }
+        return self.clarification_manager.get_remedial_concept_package(skill_id)
+
     def get_questions_for_skill(self, skill_id: str, count: int = 5, grade: Optional[int] = None, difficulty: Optional[int] = None, seed: Any = None, usage_context: Optional[str] = None, exclude_question_ids: Optional[Iterable[str]] = None, exclude_question_texts: Optional[Iterable[str]] = None, **kwargs: Any) -> List[Dict[str, Any]]:
         count=max(1,min(int(count or 5),100)); excluded_ids={str(x) for x in (exclude_question_ids or [])}; excluded_texts={str(x).strip() for x in (exclude_question_texts or [])}
         templates=self.templates_by_skill.get(str(skill_id),[])
@@ -1171,13 +1259,948 @@ class QuestionBankManager:
             "message":"QuestionBankManager جاهز: سجل السبورة يختار جميع أدوات الروضة حتى الصف الثالث من الجذر.",
         }
 
-_MANAGER: Optional[QuestionBankManager] = None
+
+class ComprehensiveQuestionBankManager(QuestionBankManager):
+    """النسخة الإنتاجية متعددة الأنواع فوق مولدات البنك الأصلية."""
+
+    def reload(self) -> Dict[str, Any]:
+        self.question_type_registry = {"types": []}
+        self.assessment_source_registry = {"sources": []}
+        self.external_items_data = {"items": []}
+        self.external_items_by_skill = {}
+        self.question_type_records = {}
+        self.bank_coverage = {
+            "skills_total": 0,
+            "skills_with_templates": 0,
+            "skills_without_templates": [],
+            "templates_total": 0,
+        }
+        result = super().reload()
+        self.question_type_registry_path = self.root_dir / "question_type_registry.json"
+        self.assessment_source_registry_path = self.root_dir / "assessment_source_registry.json"
+        self.external_items_path = self.root_dir / "external_assessment_items.json"
+        self.challenge_policy_path = self.root_dir / "challenge_test_policy.json"
+        try:
+            self.question_type_registry = _read_json(self.question_type_registry_path)
+        except Exception:
+            self.question_type_registry = {"types": []}
+        try:
+            self.assessment_source_registry = _read_json(self.assessment_source_registry_path)
+        except Exception:
+            self.assessment_source_registry = {"sources": []}
+        try:
+            self.external_items_data = _read_json(self.external_items_path)
+        except Exception:
+            self.external_items_data = {"items": []}
+        try:
+            self.challenge_policy = _read_json(self.challenge_policy_path)
+        except Exception:
+            self.challenge_policy = {
+                "default_question_count": 20,
+                "difficulty_distribution": {"3": 0.20, "4": 0.45, "5": 0.35},
+            }
+        self.external_items_by_skill = {}
+        for item in self.external_items_data.get("items", []):
+            if not isinstance(item, dict) or item.get("status") != "approved":
+                continue
+            skill_id = str(item.get("skill_id") or "").strip()
+            if skill_id:
+                self.external_items_by_skill.setdefault(skill_id, []).append(dict(item))
+
+        self.question_type_records = {
+            str(item.get("item_type")): dict(item)
+            for item in self.question_type_registry.get("types", [])
+            if isinstance(item, dict) and item.get("item_type")
+        }
+        self.bank_coverage = {
+            "skills_total": len(self.skills),
+            "skills_with_templates": len(self.templates_by_skill),
+            "skills_without_templates": sorted(set(self.skills) - set(self.templates_by_skill)),
+            "templates_total": sum(len(v) for v in self.templates_by_skill.values()),
+        }
+        return result
+
+    @staticmethod
+    def _normalize_text(value: Any) -> str:
+        if value is None:
+            return ""
+        text = str(value).strip().lower()
+        text = text.translate(str.maketrans("٠١٢٣٤٥٦٧٨٩", "0123456789"))
+        text = text.replace("،", ",").replace("٫", ".")
+        text = re.sub(r"\s+", " ", text)
+        return text
+
+    @classmethod
+    def _numeric_value(cls, value: Any) -> Optional[float]:
+        if isinstance(value, dict):
+            value = value.get("value", value.get("raw"))
+        text = cls._normalize_text(value).replace(",", ".")
+        try:
+            return float(text)
+        except Exception:
+            return None
+
+    @classmethod
+    def _normalize_collection(cls, value: Any) -> List[str]:
+        if value is None:
+            return []
+        if not isinstance(value, list):
+            value = [value]
+        return [cls._normalize_text(item) for item in value]
+
+    @classmethod
+    def _normalize_mapping(cls, value: Any) -> Dict[str, List[str]]:
+        if not isinstance(value, dict):
+            return {}
+        return {
+            cls._normalize_text(key): sorted(cls._normalize_collection(items))
+            for key, items in value.items()
+        }
+
+    def _equivalent_variant(self, correct: str) -> str:
+        text = self._normalize_text(correct)
+        try:
+            value = Fraction(text)
+            if value.denominator == 1:
+                return f"{value.numerator}/1"
+            return f"{value.numerator * 2}/{value.denominator * 2}"
+        except Exception:
+            pass
+        try:
+            value = float(text)
+            if abs(value - round(value)) < 1e-9:
+                return f"{int(round(value))}.0"
+            return f"{value:.4f}".rstrip("0")
+        except Exception:
+            return f"({correct})"
+
+    def _clean_choices(self, choices: Sequence[Any], correct: Any, rng: random.Random) -> List[str]:
+        out: List[str] = []
+        for item in list(choices or []):
+            text = _fmt(item)
+            if text not in out:
+                out.append(text)
+        correct_text = _fmt(correct)
+        if correct_text not in out:
+            out.insert(0, correct_text)
+        while len(out) < 4:
+            filler = f"بديل {len(out) + 1}"
+            if filler not in out:
+                out.append(filler)
+        out = out[:4]
+        rng.shuffle(out)
+        return out
+
+    def _shape_question(
+        self,
+        *,
+        skill: Dict[str, Any],
+        tpl: Dict[str, Any],
+        question: str,
+        answer: Any,
+        base_choices: Sequence[Any],
+        meta: Dict[str, Any],
+        rng: random.Random,
+        sequence: int,
+    ) -> Dict[str, Any]:
+        item_type = str(tpl.get("item_type") or "multiple_choice").strip().lower()
+        correct = _fmt(answer)
+        requested_item_type = item_type
+        if item_type in {"numeric_input", "number_line"} and self._numeric_value(correct) is None:
+            item_type = "fill_blank" if item_type == "numeric_input" else "short_answer"
+        choices = self._clean_choices(base_choices, correct, rng)
+        prompt = str(question).strip()
+        interaction_payload: Dict[str, Any] = {"requested_item_type": requested_item_type}
+        response_schema: Dict[str, Any] = {"type": "string"}
+        scoring_mode = str(tpl.get("scoring_mode") or "exact_match")
+        correct_response: Any = correct
+
+        if item_type == "true_false":
+            show_correct = (sequence % 2 == 0)
+            proposed = correct if show_correct else next((x for x in choices if x != correct), f"ليس {correct}")
+            prompt = f"صح أم خطأ: إجابة السؤال التالي هي «{proposed}»: {prompt}"
+            choices = ["صح", "خطأ"]
+            correct_response = "صح" if show_correct else "خطأ"
+            response_schema = {"type": "string", "enum": choices}
+            scoring_mode = "exact_match"
+
+        elif item_type == "numeric_input":
+            choices = []
+            response_schema = {"type": "number"}
+            scoring_mode = "numeric_tolerance"
+
+        elif item_type == "fill_blank":
+            prompt = f"{prompt}\nأكمل الفراغ: □"
+            choices = []
+            response_schema = {"type": "string"}
+            scoring_mode = "normalized_text"
+
+        elif item_type in {"short_answer", "oral_response", "graph_interaction"}:
+            choices = []
+            response_schema = {"type": "string"}
+            scoring_mode = "normalized_text"
+            if item_type == "oral_response":
+                prompt = f"{prompt}\nقل الإجابة شفهيًا، أو اكتبها عند تعذر الميكروفون."
+            elif item_type == "graph_interaction":
+                prompt = f"{prompt}\nحدّد القيمة أو النقطة المطلوبة من الرسم، ويمكنك استخدام السبورة."
+
+        elif item_type == "multi_select":
+            equivalent = self._equivalent_variant(correct)
+            distractors = [x for x in choices if x != correct and x != equivalent]
+            multi_choices = [correct, equivalent] + distractors[:2]
+            while len(multi_choices) < 4:
+                multi_choices.append(f"بديل {len(multi_choices) + 1}")
+            rng.shuffle(multi_choices)
+            choices = multi_choices
+            correct_response = [correct, equivalent]
+            response_schema = {"type": "array", "items": {"type": "string"}, "minItems": 2}
+            scoring_mode = "set_match"
+            prompt = f"{prompt}\nاختر كل التمثيلات الصحيحة للإجابة."
+
+        elif item_type == "ordering":
+            seq_values = meta.get("sequence") if isinstance(meta, dict) else None
+            if isinstance(seq_values, list) and seq_values:
+                ordered = [_fmt(x) for x in seq_values] + [correct]
+            else:
+                ordered = ["حدّد المعطيات", "اختر القاعدة المناسبة", "نفّذ الحل", "تحقق من النتيجة"]
+                prompt = f"{prompt}\nرتّب خطوات الحل ترتيبًا صحيحًا."
+            seen: List[str] = []
+            for item in ordered:
+                if item not in seen:
+                    seen.append(item)
+            ordered = seen
+            choices = list(ordered)
+            rng.shuffle(choices)
+            correct_response = ordered
+            response_schema = {"type": "array", "items": {"type": "string"}}
+            scoring_mode = "sequence_match"
+
+        elif item_type in {"matching", "drag_drop"}:
+            distractors = [x for x in choices if x != correct]
+            drag_items = [{"id": f"item_{i+1}", "label_ar": value, "value": value}
+                          for i, value in enumerate([correct] + distractors[:3])]
+            correct_ids = [drag_items[0]["id"]]
+            incorrect_ids = [item["id"] for item in drag_items[1:]]
+            drop_zones = [
+                {"id": "matches", "label_ar": "يحقق المطلوب"},
+                {"id": "not_matches", "label_ar": "لا يحقق المطلوب"},
+            ]
+            correct_response = {"matches": correct_ids, "not_matches": incorrect_ids}
+            interaction_payload = {
+                "drag_items": drag_items,
+                "drop_zones": drop_zones,
+            }
+            choices = []
+            response_schema = {"type": "object"}
+            scoring_mode = "pair_match"
+            prompt = f"{prompt}\nصنّف البدائل بحسب تحققها من المطلوب."
+
+        elif item_type == "number_line":
+            numeric = self._numeric_value(correct)
+            choices = []
+            interaction_payload = {
+                "min_value": min(0, int(numeric or 0) - 5),
+                "max_value": max(20, int(numeric or 0) + 5),
+                "target_value": numeric,
+            }
+            response_schema = {"type": "number"}
+            scoring_mode = "numeric_tolerance"
+            prompt = f"{prompt}\nحدّد الإجابة على خط الأعداد."
+
+        elif item_type == "whiteboard_response":
+            choices = []
+            response_schema = {"type": "object"}
+            scoring_mode = "whiteboard_evidence"
+            prompt = f"{prompt}\nحل أو مثّل الإجابة على السبورة."
+
+        elif item_type == "interactive_game":
+            choices = []
+            response_schema = {"type": "object"}
+            scoring_mode = "tool_state_match"
+            prompt = f"{prompt}\nنفّذ المطلوب باستخدام أداة الرياضيات التفاعلية."
+
+        else:
+            item_type = "multiple_choice"
+            correct_response = correct
+            response_schema = {"type": "string", "enum": choices}
+            scoring_mode = "exact_match"
+
+        return {
+            "item_type": item_type,
+            "question_type": item_type,
+            "prompt": prompt,
+            "question": prompt,
+            "question_ar": prompt,
+            "choices": choices,
+            "options": choices,
+            "correct_answer": correct_response,
+            "correct_response": correct_response,
+            "answer": correct_response,
+            "response_schema": response_schema,
+            "interaction_payload": interaction_payload,
+            "scoring_mode": scoring_mode,
+            "numeric_tolerance": float(tpl.get("numeric_tolerance", 0) or 0),
+            "partial_credit": False,
+            "renderer": tpl.get("renderer") or self.question_type_records.get(item_type, {}).get("renderer", ""),
+            "fallback_renderer": self.question_type_records.get(item_type, {}).get("fallback_renderer", ""),
+            "mastery_eligible": bool(tpl.get("mastery_eligible", True)),
+        }
+
+    def validate_question(self, q: Dict[str, Any]) -> Dict[str, Any]:
+        problems: List[str] = []
+        if not q.get("question_id"):
+            problems.append("missing_question_id")
+        if not q.get("question"):
+            problems.append("missing_question")
+        item_type = str(q.get("item_type") or "multiple_choice")
+        correct = q.get("correct_response", q.get("correct_answer"))
+        choices = q.get("choices") or []
+
+        if item_type in {"multiple_choice", "true_false"}:
+            if not isinstance(choices, list) or len(choices) < 2:
+                problems.append("choice_items_need_options")
+            if correct not in choices:
+                problems.append("answer_not_in_choices")
+        elif item_type == "multi_select":
+            if not isinstance(choices, list) or len(choices) < 2:
+                problems.append("multi_select_needs_options")
+            if not isinstance(correct, list) or not correct:
+                problems.append("multi_select_needs_correct_set")
+            elif any(item not in choices for item in correct):
+                problems.append("multi_select_answer_not_in_choices")
+        elif item_type == "ordering":
+            if not isinstance(correct, list) or len(correct) < 2:
+                problems.append("ordering_needs_sequence")
+        elif item_type in {"matching", "drag_drop"}:
+            if not isinstance(correct, dict) or not correct:
+                problems.append("matching_needs_mapping")
+        elif item_type not in self.question_type_records:
+            problems.append("unregistered_item_type")
+        if correct is None and item_type not in {"whiteboard_response", "interactive_game"}:
+            problems.append("missing_correct_response")
+        return {"success": not problems, "problems": problems}
+
+    def generate_question(
+        self,
+        skill_id: str,
+        template: Optional[Dict[str, Any]] = None,
+        seed: Any = None,
+        sequence: int = 0,
+    ) -> Dict[str, Any]:
+        skill = self.skills.get(str(skill_id))
+        if not skill:
+            return {"success": False, "message": f"المهارة غير موجودة: {skill_id}"}
+        templates = self.templates_by_skill.get(str(skill_id), [])
+        if not templates:
+            return {"success": False, "message": f"لا توجد قوالب: {skill_id}"}
+        tpl = template or templates[sequence % len(templates)]
+        rng = self._rng(seed if seed is not None else 0, skill_id, tpl.get("template_id"), sequence)
+        question, answer, choices, meta = self._generate(
+            tpl.get("generator", "concept_mcq"), skill, tpl, rng
+        )
+        shaped = self._shape_question(
+            skill=skill,
+            tpl=tpl,
+            question=question,
+            answer=answer,
+            base_choices=choices,
+            meta=meta,
+            rng=rng,
+            sequence=sequence,
+        )
+        qid_hash = hashlib.sha1(
+            f"{skill_id}|{tpl.get('template_id')}|{seed}|{sequence}|{shaped['prompt']}|{shaped['correct_response']}".encode("utf-8")
+        ).hexdigest()[:14]
+        common_errors = skill.get("common_errors") or [{}]
+        result = {
+            "success": True,
+            "question_id": f"Q-{qid_hash}",
+            "id": f"Q-{qid_hash}",
+            "question_kind": "diagnostic",
+            "source": "divid_original_generator",
+            "template_id": tpl.get("template_id"),
+            "skill_id": skill_id,
+            "skill_title": (skill.get("title") or {}).get("ar"),
+            "concept_ids": skill.get("concept_ids", []),
+            "symbol_ids": skill.get("symbol_ids", []),
+            "clarification_available": True,
+            "clarification_scored": False,
+            "clarification_is_hint": False,
+            "clarification_contract": {
+                "may_rephrase_question": True,
+                "may_explain_symbols": True,
+                "may_show_concept_aliases": True,
+                "hide_target_concept_definition": True,
+                "does_not_reduce_score": True,
+                "does_not_add_attempt": True,
+            },
+            "badge_id": (skill.get("badge_ids") or [""])[0],
+            "badge_ids": skill.get("badge_ids", []),
+            "grade_range": skill.get("grade_range", {}),
+            "difficulty": int(tpl.get("difficulty", 3) or 3),
+            "difficulty_source": tpl.get("difficulty_source", "skill_assessment_blueprint"),
+            "cognitive_domain": tpl.get("cognitive_domain", "applying"),
+            "usage_contexts": tpl.get("usage_contexts", []),
+            "error_type_if_wrong": tpl.get("error_type_if_wrong")
+                or common_errors[0].get("error_id", "NOT_FULL_MASTERY"),
+            "diagnostic_signal": common_errors[0].get("diagnostic_signal", ""),
+            "allow_dont_know": True,
+            "confirm_before_submit": True,
+            "stop_on_first_confirmed_error": True,
+            "metadata": meta,
+            "content_origin": "divid_original_generator",
+            "license": "Divid Teacher Original Content",
+            "permission_status": "owned_original",
+            "source_item_id": f"Q-{qid_hash}",
+            "attribution": "Divid Teacher",
+            "commercial_use_allowed": True,
+            "rights": {
+                "origin": "divid_original_generator",
+                "external_item_text_copied": False,
+                "production_use": "approved",
+                "license": "Divid Teacher Original Content",
+                "permission_status": "owned_original",
+                "commercial_use_allowed": True,
+            },
+            **shaped,
+        }
+        if isinstance(result.get("choices"), list) and result.get("correct_answer") in result.get("choices"):
+            result["answer_index"] = result["choices"].index(result["correct_answer"])
+        else:
+            result["answer_index"] = -1
+        validation = self.validate_question(result)
+        result["validation"] = validation
+        result["success"] = bool(validation["success"])
+        return result
+
+    def score_response(self, question: Dict[str, Any], response: Any) -> Dict[str, Any]:
+        q = dict(question or {})
+        if isinstance(response, dict) and "answer" in response:
+            board_evaluation = response.get("evaluation")
+            if isinstance(board_evaluation, dict) and isinstance(board_evaluation.get("is_correct"), bool):
+                return {
+                    "success": True,
+                    "is_correct": board_evaluation["is_correct"],
+                    "score": 1.0 if board_evaluation["is_correct"] else 0.0,
+                    "status": "correct" if board_evaluation["is_correct"] else "incorrect",
+                    "reason_ar": board_evaluation.get("reason_ar", ""),
+                    "scoring_mode": "board_evaluation",
+                }
+            response = response.get("answer")
+
+        if isinstance(response, dict) and response.get("type") == "dont_know":
+            return {"success": True, "is_correct": False, "score": 0.0, "status": "unknown", "reason_ar": "اختار الطالب لا أعلم."}
+
+        mode = str(q.get("scoring_mode") or "exact_match")
+        correct = q.get("correct_response", q.get("correct_answer"))
+        ok: Optional[bool]
+
+        if mode == "numeric_tolerance":
+            actual_num = self._numeric_value(response)
+            correct_num = self._numeric_value(correct)
+            tolerance = float(q.get("numeric_tolerance", 0) or 0)
+            ok = (
+                actual_num is not None
+                and correct_num is not None
+                and abs(actual_num - correct_num) <= tolerance
+            )
+        elif mode == "set_match":
+            ok = sorted(self._normalize_collection(response)) == sorted(self._normalize_collection(correct))
+        elif mode == "sequence_match":
+            ok = self._normalize_collection(response) == self._normalize_collection(correct)
+        elif mode == "pair_match":
+            ok = self._normalize_mapping(response) == self._normalize_mapping(correct)
+        elif mode in {"whiteboard_evidence", "tool_state_match", "rubric"}:
+            return {
+                "success": True,
+                "is_correct": None,
+                "score": None,
+                "status": "pending_external",
+                "reason_ar": "تحتاج الإجابة إلى مصحح السبورة أو مراجعة خارجية.",
+                "scoring_mode": mode,
+            }
+        else:
+            ok = self._normalize_text(response) == self._normalize_text(correct)
+
+        return {
+            "success": True,
+            "is_correct": bool(ok),
+            "score": 1.0 if ok else 0.0,
+            "status": "correct" if ok else "incorrect",
+            "reason_ar": "" if ok else "الإجابة لا تطابق دليل الإتقان المطلوب.",
+            "scoring_mode": mode,
+        }
+
+    def question_to_whiteboard_task(
+        self,
+        question: Dict[str, Any],
+        source: str = "platform",
+        include_answer: bool = False,
+        max_attempts: int = 1,
+        stop_on_first_confirmed_error: bool = True,
+    ) -> Dict[str, Any]:
+        q = dict(question or {})
+        prompt = str(q.get("prompt") or q.get("question") or "").strip()
+        item_type = str(q.get("item_type") or q.get("question_type") or "multiple_choice")
+        raw_choices = q.get("choices") or []
+        options = [
+            {"id": f"opt_{index+1}", "value": str(value), "label_ar": str(value)}
+            for index, value in enumerate(raw_choices)
+        ]
+        payload = q.get("interaction_payload") if isinstance(q.get("interaction_payload"), dict) else {}
+
+        if item_type == "multiple_choice":
+            response_mode = "single_choice"
+        elif item_type == "multi_select":
+            response_mode = "multiple_choice"
+        elif item_type == "true_false":
+            response_mode = "true_false"
+        elif item_type in {"numeric_input", "number_line"}:
+            response_mode = "numeric_response"
+        elif item_type in {"fill_blank", "short_answer", "oral_response", "graph_interaction"}:
+            response_mode = "text_response"
+        elif item_type == "ordering":
+            response_mode = "ordering"
+        elif item_type in {"matching", "drag_drop"}:
+            response_mode = "drag_drop"
+        elif item_type == "whiteboard_response":
+            response_mode = "drawing_response"
+        elif item_type == "interactive_game":
+            response_mode = "drawing_response"
+        else:
+            response_mode = "text_response"
+
+        scoring_mode = {
+            "single_choice": "exact",
+            "multiple_choice": "unordered_set",
+            "true_false": "exact",
+            "numeric_response": "numeric",
+            "text_response": "exact",
+            "ordering": "ordered",
+            "drag_drop": "mapping",
+            "drawing_response": "external",
+        }[response_mode]
+
+        if item_type in {"whiteboard_response", "interactive_game"}:
+            scoring_mode = "external"
+
+        return {
+            "task_id": str(q.get("question_id") or f"WB-{hashlib.sha1(prompt.encode('utf-8')).hexdigest()[:12]}"),
+            "question_id": str(q.get("question_id") or ""),
+            "skill_id": str(q.get("skill_id") or ""),
+            "badge_id": str(q.get("badge_id") or ""),
+            "source": str(source or "platform"),
+            "instruction_ar": prompt,
+            "response_mode": response_mode,
+            "options": options,
+            "drag_items": payload.get("drag_items", []),
+            "drop_zones": payload.get("drop_zones", []),
+            "correct_answer": q.get("correct_response", q.get("correct_answer")) if include_answer else None,
+            "scoring": {
+                "mode": scoring_mode,
+                "tolerance": float(q.get("numeric_tolerance", 0) or 0),
+                "incorrect_feedback_ar": "الإجابة غير صحيحة.",
+            },
+            "feedback_policy": {"show_immediate": bool(include_answer), "show_correct_answer": False},
+            "allowed_tools": ["pen", "highlighter", "eraser", "select", "text"],
+            "clear_page": True,
+            "max_attempts": max(1, int(max_attempts or 1)),
+            "stop_on_first_confirmed_error": bool(stop_on_first_confirmed_error),
+            "metadata": {
+                "item_type": item_type,
+                "difficulty": q.get("difficulty"),
+                "difficulty_source": q.get("difficulty_source"),
+                "error_type_if_wrong": q.get("error_type_if_wrong", ""),
+                "content_origin": q.get("content_origin", ""),
+                "mastery_eligible": q.get("mastery_eligible", True),
+            },
+        }
+
+
+    def _external_runtime_question(self, item: Dict[str, Any]) -> Dict[str, Any]:
+        choices = list(item.get("choices") or [])
+        correct = item.get("correct_response", item.get("correct_answer"))
+        question_id = str(item.get("external_item_id") or item.get("question_id") or item.get("source_item_id") or "")
+        result = {
+            "success": True,
+            "version": VERSION,
+            "question_id": question_id,
+            "item_id": question_id,
+            "skill_id": str(item.get("skill_id") or ""),
+            "template_id": str(item.get("template_id") or ""),
+            "item_type": str(item.get("item_type") or "multiple_choice"),
+            "renderer": str(item.get("renderer") or item.get("item_type") or "multiple_choice"),
+            "scoring_mode": str(item.get("scoring_mode") or "exact_match"),
+            "difficulty": _safe_int(item.get("difficulty"), 3),
+            "difficulty_source": "external_item_validated",
+            "cognitive_domain": str(item.get("cognitive_domain") or "applying"),
+            "usage_contexts": list(item.get("usage_contexts") or ["diagnostic", "practice"]),
+            "question": str(item.get("question") or ""),
+            "prompt": str(item.get("question") or ""),
+            "question_ar": str(item.get("question_ar") or item.get("question") or ""),
+            "choices": choices,
+            "correct_answer": correct,
+            "answer": correct,
+            "correct_response": correct,
+            "numeric_tolerance": item.get("numeric_tolerance"),
+            "partial_credit": item.get("partial_credit", False),
+            "interaction_payload": dict(item.get("interaction_payload") or {}),
+            "response_schema": dict(item.get("response_schema") or {}),
+            "error_type_if_wrong": str(item.get("error_type_if_wrong") or "NOT_FULL_MASTERY"),
+            "diagnostic_signal": str(item.get("diagnostic_signal") or ""),
+            "allow_dont_know": True,
+            "confirm_before_submit": True,
+            "stop_on_first_confirmed_error": True,
+            "mastery_eligible": bool(item.get("mastery_eligible", True)),
+            "content_origin": "external_open_resource",
+            "source_id": str(item.get("source_id") or ""),
+            "source_item_id": str(item.get("source_item_id") or ""),
+            "attribution": str(item.get("attribution") or ""),
+            "license": str(item.get("license") or ""),
+            "permission_status": str(item.get("permission_status") or ""),
+            "commercial_use_allowed": item.get("commercial_use_allowed"),
+            "language": str(item.get("language") or "ar"),
+            "rights": {
+                "origin": "external_open_resource",
+                "external_item_text_copied": bool(item.get("adapted_or_verbatim") == "verbatim"),
+                "production_use": "approved",
+                "license": str(item.get("license") or ""),
+                "permission_status": str(item.get("permission_status") or ""),
+                "commercial_use_allowed": item.get("commercial_use_allowed"),
+                "attribution": str(item.get("attribution") or ""),
+            },
+        }
+        if choices and correct in choices:
+            result["answer_index"] = choices.index(correct)
+        result["validation"] = self.validate_question(result)
+        if not result["validation"].get("success"):
+            result["success"] = False
+        return result
+
+    def get_questions_for_skill(
+        self,
+        skill_id: str,
+        count: int = 5,
+        grade: Optional[int] = None,
+        difficulty: Optional[int] = None,
+        seed: Any = None,
+        usage_context: Optional[str] = None,
+        exclude_question_ids: Optional[Iterable[str]] = None,
+        exclude_question_texts: Optional[Iterable[str]] = None,
+        prefer_external: bool = True,
+        external_ratio: float = 0.35,
+        allow_english_external: bool = False,
+        commercial_mode: bool = True,
+        **kwargs: Any,
+    ) -> List[Dict[str, Any]]:
+        count = max(1, min(int(count or 5), 100))
+        excluded_ids = {str(x) for x in (exclude_question_ids or [])}
+        excluded_texts = {str(x).strip() for x in (exclude_question_texts or [])}
+        selected: List[Dict[str, Any]] = []
+        if prefer_external:
+            candidates = []
+            for item in self.external_items_by_skill.get(str(skill_id), []):
+                if commercial_mode and item.get("commercial_use_allowed") is False:
+                    continue
+                language = str(item.get("language") or "ar").lower()
+                if language != "ar" and not allow_english_external:
+                    continue
+                if usage_context and usage_context not in (item.get("usage_contexts") or []):
+                    continue
+                if difficulty is not None and abs(_safe_int(item.get("difficulty"), 3) - int(difficulty)) > 1:
+                    continue
+                qid = str(item.get("external_item_id") or item.get("question_id") or item.get("source_item_id") or "")
+                qtext = str(item.get("question") or "").strip()
+                if not qid or not qtext or qid in excluded_ids or qtext in excluded_texts:
+                    continue
+                candidates.append(item)
+            rng = random.Random(str(seed) + "|external|" + str(skill_id))
+            rng.shuffle(candidates)
+            external_target = min(len(candidates), max(0, round(count * max(0.0, min(float(external_ratio), 1.0)))))
+            for item in candidates[:external_target]:
+                q = self._external_runtime_question(item)
+                if q.get("success"):
+                    selected.append(q)
+        generated_needed = count - len(selected)
+        if generated_needed > 0:
+            generated = super().get_questions_for_skill(
+                skill_id=skill_id,
+                count=generated_needed,
+                grade=grade,
+                difficulty=difficulty,
+                seed=seed,
+                usage_context=usage_context,
+                exclude_question_ids=excluded_ids | {q.get("question_id", "") for q in selected},
+                exclude_question_texts=excluded_texts | {q.get("question", "") for q in selected},
+                **kwargs,
+            )
+            selected.extend(generated)
+        return selected[:count]
+
+
+    @staticmethod
+    def question_fingerprint(question: Dict[str, Any]) -> str:
+        """بصمة مستقرة تمنع تكرار نص السؤال حتى لو تغير question_id."""
+        skill_id = str(question.get("skill_id") or "").strip()
+        text = re.sub(
+            r"\s+",
+            " ",
+            str(question.get("question") or question.get("prompt") or "").strip().lower(),
+        )
+        return hashlib.sha256(f"{skill_id}|{text}".encode("utf-8")).hexdigest()[:24]
+
+    def get_challenge_questions(
+        self,
+        skill_ids: Optional[Sequence[str]] = None,
+        badge_id: str = "",
+        count: Optional[int] = None,
+        grade: Optional[int] = None,
+        seed: Any = None,
+        exclude_question_ids: Optional[Iterable[str]] = None,
+        exclude_question_texts: Optional[Iterable[str]] = None,
+        exclude_fingerprints: Optional[Iterable[str]] = None,
+        external_ratio: Optional[float] = None,
+        **kwargs: Any,
+    ) -> List[Dict[str, Any]]:
+        """
+        يبني اختبار تحدٍّ متوازنًا عبر المهارات والصعوبة، بلا تلميحات،
+        ويولد بدائل جديدة قبل السماح بتكرار سؤال سابق.
+        """
+        policy = dict(getattr(self, "challenge_policy", {}) or {})
+        target_count = int(
+            count
+            or policy.get("default_question_count", 20)
+            or 20
+        )
+        target_count = max(
+            int(policy.get("minimum_question_count", 12) or 12),
+            min(
+                target_count,
+                int(policy.get("maximum_question_count", 40) or 40),
+            ),
+        )
+
+        resolved_skills: List[str] = []
+        for skill_id in list(skill_ids or []):
+            key = str(skill_id or "").strip()
+            if key in self.skills and key not in resolved_skills:
+                resolved_skills.append(key)
+
+        if not resolved_skills and badge_id:
+            for skill_id in self.skills_by_badge.get(str(badge_id), []):
+                if skill_id in self.skills and skill_id not in resolved_skills:
+                    resolved_skills.append(skill_id)
+
+        if grade is not None:
+            filtered = []
+            for skill_id in resolved_skills:
+                grade_range = self.skills[skill_id].get("grade_range") or {}
+                minimum = _safe_int(grade_range.get("min"), 0)
+                maximum = _safe_int(grade_range.get("max"), 12)
+                if minimum <= int(grade) <= maximum:
+                    filtered.append(skill_id)
+            resolved_skills = filtered or resolved_skills
+
+        if not resolved_skills:
+            return []
+
+        excluded_ids = {str(item) for item in (exclude_question_ids or [])}
+        excluded_texts = {
+            re.sub(r"\s+", " ", str(item).strip())
+            for item in (exclude_question_texts or [])
+        }
+        excluded_fps = {str(item) for item in (exclude_fingerprints or [])}
+
+        difficulty_distribution = policy.get("difficulty_distribution") or {
+            "3": 0.20,
+            "4": 0.45,
+            "5": 0.35,
+        }
+        difficulty_sequence: List[int] = []
+        for value, ratio in difficulty_distribution.items():
+            number = max(1, round(target_count * float(ratio)))
+            difficulty_sequence.extend([int(value)] * number)
+        while len(difficulty_sequence) < target_count:
+            difficulty_sequence.append(5)
+        difficulty_sequence = difficulty_sequence[:target_count]
+
+        rng = random.Random(f"{seed}|challenge|{badge_id}|{'|'.join(resolved_skills)}")
+        rng.shuffle(difficulty_sequence)
+
+        ratio = (
+            float(external_ratio)
+            if external_ratio is not None
+            else float(
+                (policy.get("pool_rules") or {}).get(
+                    "external_ratio_when_available", 0.25
+                )
+            )
+        )
+
+        selected: List[Dict[str, Any]] = []
+        selected_fps: set[str] = set()
+        attempts = 0
+        max_attempts = target_count * max(50, len(resolved_skills) * 12)
+
+        while len(selected) < target_count and attempts < max_attempts:
+            skill_id = resolved_skills[attempts % len(resolved_skills)]
+            difficulty = difficulty_sequence[len(selected) % len(difficulty_sequence)]
+            variant_seed = f"{seed}|challenge|{attempts}|{skill_id}|{difficulty}"
+
+            challenge_templates = [
+                template
+                for template in self.templates_by_skill.get(skill_id, [])
+                if "challenge" in (template.get("usage_contexts") or [])
+                and bool(template.get("mastery_eligible", True))
+                and str(template.get("scoring_mode") or "") not in {
+                    "whiteboard_evidence",
+                    "tool_state_match",
+                    "rubric",
+                    "external",
+                }
+            ]
+            challenge_templates.sort(
+                key=lambda template: (
+                    abs(_safe_int(template.get("difficulty"), 3) - difficulty),
+                    str(template.get("challenge_role") or template.get("template_id") or ""),
+                )
+            )
+            if not challenge_templates:
+                attempts += 1
+                continue
+
+            # ندور بين القوالب المتقاربة في الصعوبة بدل اختيار القالب الأول دائمًا.
+            close_templates = [
+                template
+                for template in challenge_templates
+                if abs(_safe_int(template.get("difficulty"), 3) - difficulty) <= 1
+            ] or challenge_templates
+            template = close_templates[attempts % len(close_templates)]
+            question = self.generate_question(
+                skill_id=skill_id,
+                template=template,
+                seed=variant_seed,
+                sequence=attempts,
+            )
+            attempts += 1
+            if not question.get("success"):
+                continue
+            question = dict(question)
+            if not bool(question.get("mastery_eligible", True)):
+                continue
+            if str(question.get("scoring_mode")) in {
+                "whiteboard_evidence",
+                "tool_state_match",
+                "rubric",
+                "external",
+            }:
+                continue
+
+            fingerprint = self.question_fingerprint(question)
+            if fingerprint in excluded_fps or fingerprint in selected_fps:
+                continue
+
+            question["question_fingerprint"] = fingerprint
+            question["question_kind"] = "challenge"
+            question["challenge_test"] = True
+            question["challenge_index"] = len(selected) + 1
+            question["allow_dont_know"] = False
+            question["allow_hints"] = False
+            question["stop_on_first_confirmed_error"] = False
+            selected.append(question)
+            selected_fps.add(fingerprint)
+
+        return selected
+
+    def get_challenge_test_questions(
+        self,
+        skill_ids: Optional[Sequence[str]] = None,
+        badge_id: str = "",
+        count: Optional[int] = None,
+        **kwargs: Any,
+    ) -> List[Dict[str, Any]]:
+        return self.get_challenge_questions(
+            skill_ids=skill_ids,
+            badge_id=badge_id,
+            count=count,
+            **kwargs,
+        )
+
+    def question_bank_capacity(self) -> Dict[str, Any]:
+        challenge_templates = sum(
+            1
+            for templates in self.templates_by_skill.values()
+            for template in templates
+            if "challenge" in (template.get("usage_contexts") or [])
+        )
+        return {
+            "skills_count": len(self.skills),
+            "templates_total": sum(
+                len(templates) for templates in self.templates_by_skill.values()
+            ),
+            "templates_per_skill_min": min(
+                (len(templates) for templates in self.templates_by_skill.values()),
+                default=0,
+            ),
+            "challenge_templates_total": challenge_templates,
+            "challenge_templates_per_skill": (
+                challenge_templates // len(self.skills)
+                if self.skills
+                else 0
+            ),
+            "external_items_total": sum(
+                len(items) for items in self.external_items_by_skill.values()
+            ),
+            "external_skills_covered": len(self.external_items_by_skill),
+            "seeded_generation": True,
+            "anti_repetition_supported": True,
+            "closed_for_production": True,
+        }
+
+    def summary(self) -> Dict[str, Any]:
+        base = super().summary()
+        type_counts: Dict[str, int] = {}
+        difficulty_counts: Dict[str, int] = {}
+        for templates in self.templates_by_skill.values():
+            for template in templates:
+                item_type = str(template.get("item_type") or "multiple_choice")
+                type_counts[item_type] = type_counts.get(item_type, 0) + 1
+                difficulty = str(template.get("difficulty", ""))
+                difficulty_counts[difficulty] = difficulty_counts.get(difficulty, 0) + 1
+        base.update({
+            "version": VERSION,
+            "skills_with_templates": len(self.templates_by_skill),
+            "skills_without_templates": self.bank_coverage.get("skills_without_templates", []),
+            "question_types_registered": len(self.question_type_records),
+            "question_type_counts": type_counts,
+            "difficulty_counts": difficulty_counts,
+            "source_registry_loaded": bool(self.assessment_source_registry.get("sources")),
+            "assessment_sources_count": len(self.assessment_source_registry.get("sources", [])),
+            "external_items_approved_count": sum(len(v) for v in self.external_items_by_skill.values()),
+            "external_skills_covered_count": len(self.external_items_by_skill),
+            "external_import_pipeline_ready": True,
+            "challenge_policy_loaded": bool(getattr(self, "challenge_policy", {})),
+            "math_bank_capacity": self.question_bank_capacity(),
+            "complete_k12_question_bank": (
+                len(self.templates_by_skill) == len(self.skills)
+                and not self.bank_coverage.get("skills_without_templates")
+            ),
+            "concept_dictionary_loaded": bool(self.clarification_manager),
+            "concept_dictionary_error": self.clarification_error,
+            "clarification_scored": False,
+            "clarification_is_hint": False,
+            "message": "بنك الأسئلة K–12 مكتمل بالقوالب متعددة الأنواع، والصعوبة مأخوذة من مخطط المهارة ثم يختارها المدير.",
+        })
+        return base
+
+
+_MANAGER: Optional[ComprehensiveQuestionBankManager] = None
 _LOCK=threading.Lock()
 
-def get_manager() -> QuestionBankManager:
+def get_manager() -> ComprehensiveQuestionBankManager:
     global _MANAGER
     with _LOCK:
-        if _MANAGER is None: _MANAGER=QuestionBankManager()
+        if _MANAGER is None: _MANAGER=ComprehensiveQuestionBankManager()
         return _MANAGER
 
 def get_badge_diagnostic_questions(subject="math",grade=None,badge_id="",count=5,difficulty=None,skill_id="",**kwargs):
@@ -1192,6 +2215,27 @@ def get_skills_for_badge(badge_id, grade=None):
 def get_mastery_units(grade=None, learning_mode="gap_recovery"):
     return get_manager().get_mastery_units(grade=grade, learning_mode=learning_mode)
 
+
+def get_challenge_questions(skill_ids=None,badge_id="",count=None,**kwargs):
+    return get_manager().get_challenge_questions(
+        skill_ids=skill_ids,
+        badge_id=badge_id,
+        count=count,
+        **kwargs,
+    )
+
+def get_challenge_test_questions(skill_ids=None,badge_id="",count=None,**kwargs):
+    return get_manager().get_challenge_test_questions(
+        skill_ids=skill_ids,
+        badge_id=badge_id,
+        count=count,
+        **kwargs,
+    )
+
+def question_bank_capacity():
+    return get_manager().question_bank_capacity()
+
+
 def get_questions_for_badge(badge_id,count=5,**kwargs):
     return get_manager().get_questions_for_badge(badge_id,count=count,**kwargs)
 
@@ -1212,5 +2256,20 @@ def get_whiteboard_task_for_feature(feature_id, **kwargs):
 def get_whiteboard_task_for_skill(skill_id, **kwargs):
     return get_manager().get_whiteboard_task_for_skill(skill_id, **kwargs)
 
+def clarify_question(question, **kwargs):
+    return get_manager().clarify_question(question, **kwargs)
+
+def get_concept_dictionary_entry(concept_id):
+    return get_manager().get_concept_dictionary_entry(concept_id)
+
+def get_symbol_dictionary_entry(symbol_id):
+    return get_manager().get_symbol_dictionary_entry(symbol_id)
+
+def get_remedial_concept_package(skill_id):
+    return get_manager().get_remedial_concept_package(skill_id)
+
+def score_response(question, response):
+    return get_manager().score_response(question, response)
+
 def summary():
     return get_manager().summary()

question_clarification_manager.py

@@ -0,0 +1,439 @@
+# question_clarification_manager.py
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+
+VERSION = "question_clarification_manager_v1_math_concepts_symbols"
+
+
+def _read_json(path: Path) -> Dict[str, Any]:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError(f"جذر الملف يجب أن يكون كائنًا: {path.name}")
+    return data
+
+
+def _normalize_text(value: Any) -> str:
+    text = str(value or "").strip()
+    text = re.sub(r"[\u064B-\u065F\u0670]", "", text)
+    text = text.replace("ـ", "")
+    return re.sub(r"\s+", " ", text)
+
+
+class QuestionClarificationManager:
+    """
+    طبقة عدالة لغوية مستقلة عن التلميحات.
+
+    - تعيد صياغة فعل المطلوب دون شرح طريقة الحل.
+    - تشرح الرموز الموجودة في السؤال.
+    - تعرض أسماء المفهوم البديلة.
+    - تمنع عرض تعريف المفهوم إذا كان التعريف نفسه هو موضع التقييم.
+    - لا تغيّر العلامة ولا عدد المحاولات.
+    """
+
+    COMMAND_RULES = [
+        (r"^\s*أوجد", "المطلوب: احسب أو حدّد القيمة المطلوبة."),
+        (r"^\s*احسب", "المطلوب: نفّذ العملية واكتب الناتج النهائي."),
+        (r"^\s*قارن", "المطلوب: حدّد أي القيمتين أكبر أو أصغر، أو هل هما متساويتان."),
+        (r"^\s*رت[ّ]?ب", "المطلوب: ضع القيم حسب الترتيب المذكور في السؤال."),
+        (r"^\s*قر[ّ]?ب", "المطلوب: اكتب قيمة تقريبية حسب المنزلة المحددة."),
+        (r"^\s*حل(?:\s+المعادلة)?", "المطلوب: أوجد قيمة المتغير التي تجعل العبارة صحيحة."),
+        (r"^\s*بس[ّ]?ط", "المطلوب: اكتب التعبير في صورة أبسط مع بقاء القيمة نفسها."),
+        (r"^\s*حل[ّ]?ل", "المطلوب: فكّك العدد أو التعبير إلى عوامله أو أجزائه المطلوبة."),
+        (r"^\s*مث[ّ]?ل", "المطلوب: اعرض الفكرة بالرسم أو الجدول أو الرمز المطلوب."),
+        (r"^\s*فس[ّ]?ر", "المطلوب: اكتب سببًا رياضيًا يوضح لماذا النتيجة صحيحة."),
+        (r"^\s*برهن", "المطلوب: اكتب خطوات منطقية تثبت العبارة دون الاكتفاء بالجواب."),
+        (r"^\s*استنتج", "المطلوب: استخدم المعطيات للوصول إلى نتيجة جديدة."),
+        (r"^\s*حد[ّ]?د", "المطلوب: اختر أو اكتب العنصر الذي يحقق الشرط."),
+        (r"^\s*اختر", "المطلوب: اختر البديل الذي يحقق شروط السؤال."),
+        (r"^\s*قد[ّ]?ر", "المطلوب: أوجد قيمة قريبة تساعد على التحقق، لا قيمة دقيقة بالضرورة."),
+    ]
+
+    REPHRASE_RULES = [
+        (r"\bأوجد\b", "احسب أو حدّد"),
+        (r"\bقارن\b", "بيّن العلاقة"),
+        (r"\bرت[ّ]?ب\b", "ضع بالترتيب"),
+        (r"\bقر[ّ]?ب\b", "اكتب القيمة التقريبية لـ"),
+        (r"\bبس[ّ]?ط\b", "اكتب في صورة أبسط"),
+        (r"\bفس[ّ]?ر\b", "اشرح السبب"),
+        (r"\bبرهن\b", "أثبت بخطوات منطقية"),
+        (r"\bحد[ّ]?د\b", "عيّن"),
+    ]
+
+    CHARACTER_SYMBOLS = {
+        "+": "SYM_PLUS",
+        "-": "SYM_MINUS",
+        "−": "SYM_MINUS",
+        "±": "SYM_PLUS_MINUS",
+        "×": "SYM_MULTIPLY_CROSS",
+        "·": "SYM_MULTIPLY_DOT",
+        "÷": "SYM_DIVIDE",
+        "=": "SYM_EQUALS",
+        "≠": "SYM_NOT_EQUALS",
+        "<": "SYM_LESS_THAN",
+        ">": "SYM_GREATER_THAN",
+        "≤": "SYM_LESS_EQUAL",
+        "≥": "SYM_GREATER_EQUAL",
+        "≈": "SYM_APPROX",
+        "≡": "SYM_EQUIVALENT",
+        "%": "SYM_PERCENT",
+        "‰": "SYM_PER_MILLE",
+        "∝": "SYM_PROPORTIONAL",
+        "√": "SYM_SQUARE_ROOT",
+        "π": "SYM_PI",
+        "∞": "SYM_INFINITY",
+        "Σ": "SYM_SUMMATION",
+        "Π": "SYM_PRODUCT",
+        "∅": "SYM_EMPTY_SET",
+        "φ": "SYM_PHI",
+        "ϕ": "SYM_PHI",
+        "⌀": "SYM_DIAMETER",
+        "∈": "SYM_ELEMENT_OF",
+        "∉": "SYM_NOT_ELEMENT_OF",
+        "⊂": "SYM_SUBSET",
+        "⊆": "SYM_SUBSET_EQUAL",
+        "⊃": "SYM_SUPERSET",
+        "∪": "SYM_UNION",
+        "∩": "SYM_INTERSECTION",
+        "∀": "SYM_FOR_ALL",
+        "∃": "SYM_EXISTS",
+        "¬": "SYM_NOT",
+        "∧": "SYM_AND",
+        "∨": "SYM_OR",
+        "⇒": "SYM_IMPLIES",
+        "⇔": "SYM_IFF",
+        "∴": "SYM_THEREFORE",
+        "ℕ": "SYM_NATURAL_NUMBERS",
+        "ℤ": "SYM_INTEGERS",
+        "ℚ": "SYM_RATIONALS",
+        "ℝ": "SYM_REALS",
+        "ℂ": "SYM_COMPLEXES",
+        "∠": "SYM_ANGLE",
+        "°": "SYM_DEGREE",
+        "⟂": "SYM_PERPENDICULAR",
+        "∥": "SYM_PARALLEL",
+        "≅": "SYM_CONGRUENT",
+        "∼": "SYM_SIMILAR",
+        "△": "SYM_TRIANGLE",
+        "Δ": "SYM_DELTA",
+        "↦": "SYM_MAPSTO",
+        "→": "SYM_ARROW",
+        "∘": "SYM_COMPOSITION",
+        "∫": "SYM_INTEGRAL",
+        "∂": "SYM_PARTIAL",
+        "∇": "SYM_NABLA",
+    }
+
+    def __init__(self, root_dir: Optional[str | Path] = None) -> None:
+        self.version = VERSION
+        self.root_dir = Path(root_dir or Path(__file__).resolve().parent)
+        self.concepts_path = self.root_dir / "math_concepts_global.json"
+        self.symbols_path = self.root_dir / "math_symbols_global.json"
+        self.skills_path = self.root_dir / "math_skills_global.json"
+        self._lock = threading.RLock()
+        self.reload()
+
+    def reload(self) -> Dict[str, Any]:
+        with self._lock:
+            self.concepts_data = _read_json(self.concepts_path)
+            self.symbols_data = _read_json(self.symbols_path)
+            self.skills_data = _read_json(self.skills_path)
+            self.concepts = {
+                str(item["concept_id"]): item
+                for item in self.concepts_data.get("concepts", [])
+            }
+            self.symbols = {
+                str(item["symbol_id"]): item
+                for item in self.symbols_data.get("symbols", [])
+            }
+            self.skills = {
+                str(item["skill_id"]): item
+                for item in self.skills_data.get("skills", [])
+            }
+            self.concept_ids_by_skill: Dict[str, List[str]] = {}
+            for skill_id, skill in self.skills.items():
+                self.concept_ids_by_skill[skill_id] = [
+                    str(value) for value in (skill.get("concept_ids") or [])
+                    if str(value) in self.concepts
+                ]
+            return self.summary()
+
+    def summary(self) -> Dict[str, Any]:
+        return {
+            "version": self.version,
+            "concepts_count": len(self.concepts),
+            "symbols_count": len(self.symbols),
+            "skills_count": len(self.skills),
+            "clarification_scored": False,
+            "clarification_is_hint": False,
+        }
+
+    def get_symbol(self, symbol_id: str) -> Dict[str, Any]:
+        item = self.symbols.get(str(symbol_id))
+        return dict(item) if item else {}
+
+    def get_concept(self, concept_id: str) -> Dict[str, Any]:
+        item = self.concepts.get(str(concept_id))
+        return dict(item) if item else {}
+
+    def get_concepts_for_skill(self, skill_id: str) -> List[Dict[str, Any]]:
+        return [
+            dict(self.concepts[concept_id])
+            for concept_id in self.concept_ids_by_skill.get(str(skill_id), [])
+            if concept_id in self.concepts
+        ]
+
+    def detect_symbol_ids(
+        self,
+        question_text: str,
+        skill_id: str = "",
+    ) -> List[str]:
+        text = str(question_text or "")
+        found: List[str] = []
+
+        for character, symbol_id in self.CHARACTER_SYMBOLS.items():
+            if character in text and symbol_id in self.symbols and symbol_id not in found:
+                found.append(symbol_id)
+
+        # أنماط نصية لا تعتمد على محرف واحد.
+        patterns = [
+            (r"\bf\s*\(", "SYM_FUNCTION"),
+            (r"\b(?:log)\b", "SYM_LOG"),
+            (r"\b(?:ln)\b", "SYM_LN"),
+            (r"\blim\b", "SYM_LIMIT"),
+            (r"\bdy\s*/\s*dx\b", "SYM_DERIVATIVE_LEIBNIZ"),
+            (r"\bf\s*[′']", "SYM_DERIVATIVE_PRIME"),
+            (r"\bP\s*\([^)]*\|[^)]*\)", "SYM_CONDITIONAL_PROBABILITY"),
+            (r"\bP\s*\(", "SYM_PROBABILITY"),
+            (r"\bx̄\b", "SYM_MEAN"),
+            (r"\bdet\s*\(", "SYM_DETERMINANT"),
+        ]
+        for pattern, symbol_id in patterns:
+            if re.search(pattern, text, flags=re.IGNORECASE) and symbol_id in self.symbols:
+                if symbol_id not in found:
+                    found.append(symbol_id)
+
+        skill = self.skills.get(str(skill_id), {})
+        for symbol_id in skill.get("symbol_ids") or []:
+            if symbol_id in self.symbols and symbol_id not in found:
+                found.append(symbol_id)
+
+        return found
+
+    def get_symbol_cards(
+        self,
+        question_text: str,
+        skill_id: str = "",
+        assessed_symbol_ids: Optional[Iterable[str]] = None,
+    ) -> List[Dict[str, Any]]:
+        assessed = {str(value) for value in (assessed_symbol_ids or [])}
+        cards: List[Dict[str, Any]] = []
+        for symbol_id in self.detect_symbol_ids(question_text, skill_id):
+            item = self.symbols.get(symbol_id)
+            if not item:
+                continue
+            card = {
+                "symbol_id": symbol_id,
+                "display": item.get("display"),
+                "name_ar": item.get("name_ar"),
+                "spoken_ar": item.get("spoken_ar"),
+                "clarification_scored": False,
+                "clarification_is_hint": False,
+            }
+            if symbol_id in assessed:
+                card["definition_hidden"] = True
+                card["message_ar"] = "معنى هذا الرمز هو جزء من المطلوب في السؤال، لذلك لا يظهر التعريف الآن."
+            else:
+                card["definition_hidden"] = False
+                card["student_definition_ar"] = item.get("student_definition_ar")
+                card["examples"] = item.get("examples") or []
+                card["common_confusions"] = item.get("common_confusions") or []
+            cards.append(card)
+        return cards
+
+    def get_concept_cards(
+        self,
+        skill_id: str,
+        assessed_concept_ids: Optional[Iterable[str]] = None,
+        assessment_mode: bool = True,
+    ) -> List[Dict[str, Any]]:
+        assessed = {str(value) for value in (assessed_concept_ids or [])}
+        cards: List[Dict[str, Any]] = []
+        for concept in self.get_concepts_for_skill(skill_id):
+            concept_id = str(concept.get("concept_id"))
+            card = {
+                "concept_id": concept_id,
+                "canonical_name_ar": concept.get("canonical_name_ar"),
+                "aliases_ar": concept.get("aliases_ar") or [],
+                "symbol_ids": concept.get("symbol_ids") or [],
+                "clarification_scored": False,
+                "clarification_is_hint": False,
+            }
+            hide = (
+                assessment_mode
+                and concept_id in assessed
+                and bool(
+                    (concept.get("clarification_policy") or {}).get(
+                        "hide_full_definition_when_concept_itself_is_assessed",
+                        True,
+                    )
+                )
+            )
+            if hide:
+                card["definition_hidden"] = True
+                card["message_ar"] = "التعريف الكامل مخفي لأن المفهوم نفسه هو موضع التقييم."
+            else:
+                card["definition_hidden"] = False
+                card["definition_ar"] = concept.get("definition_ar")
+                card["student_friendly_explanation_ar"] = concept.get(
+                    "student_friendly_explanation_ar"
+                )
+            cards.append(card)
+        return cards
+
+    def instruction_clarification(self, question_text: str) -> str:
+        text = _normalize_text(question_text)
+        for pattern, explanation in self.COMMAND_RULES:
+            if re.search(pattern, text):
+                return explanation
+        return "المطلوب: اقرأ المعطيات وحدد ما الذي يجب كتابته أو اختياره، دون تغيير طريقة الحل."
+
+    def alternative_wording(self, question_text: str) -> str:
+        text = _normalize_text(question_text)
+        alternative = text
+        for pattern, replacement in self.REPHRASE_RULES:
+            if re.search(pattern, alternative):
+                alternative = re.sub(pattern, replacement, alternative, count=1)
+                break
+        return alternative
+
+    def clarify_question(
+        self,
+        question_text: str,
+        skill_id: str = "",
+        assessed_concept_ids: Optional[Iterable[str]] = None,
+        assessed_symbol_ids: Optional[Iterable[str]] = None,
+        assessment_mode: bool = True,
+    ) -> Dict[str, Any]:
+        original = _normalize_text(question_text)
+        alternative = self.alternative_wording(original)
+        event_id = hashlib.sha256(
+            f"{skill_id}|{original}|{datetime.now(timezone.utc).isoformat()}".encode("utf-8")
+        ).hexdigest()[:20]
+        return {
+            "success": True,
+            "clarification_event_id": f"CLARIFY-{event_id}",
+            "original_question_ar": original,
+            "alternative_wording_ar": alternative,
+            "instruction_clarification_ar": self.instruction_clarification(original),
+            "concept_cards": self.get_concept_cards(
+                skill_id=skill_id,
+                assessed_concept_ids=assessed_concept_ids,
+                assessment_mode=assessment_mode,
+            ),
+            "symbol_cards": self.get_symbol_cards(
+                question_text=original,
+                skill_id=skill_id,
+                assessed_symbol_ids=assessed_symbol_ids,
+            ),
+            "evaluation_effect": {
+                "scored": False,
+                "counts_as_hint": False,
+                "reduces_mark": False,
+                "adds_attempt": False,
+            },
+            "safety_rules": {
+                "does_not_show_correct_answer": True,
+                "does_not_remove_options": True,
+                "does_not_name_required_operation_when_that_is_assessed": True,
+            },
+        }
+
+    def get_remedial_concept_package(self, skill_id: str) -> Dict[str, Any]:
+        concepts = self.get_concepts_for_skill(skill_id)
+        symbol_ids: List[str] = []
+        for concept in concepts:
+            for symbol_id in concept.get("symbol_ids") or []:
+                if symbol_id not in symbol_ids:
+                    symbol_ids.append(symbol_id)
+        return {
+            "success": bool(concepts),
+            "skill_id": skill_id,
+            "concepts": concepts,
+            "symbols": [
+                dict(self.symbols[symbol_id])
+                for symbol_id in symbol_ids
+                if symbol_id in self.symbols
+            ],
+            "lesson_requirements": {
+                "must_explain_concept_names": True,
+                "must_explain_symbols_before_use": True,
+                "text_explanation_required": True,
+                "audio_explanation_supported": True,
+                "micro_video_supported": True,
+                "final_concept_check_required": True,
+            },
+        }
+
+    def build_clarification_usage_event(
+        self,
+        student_id: str,
+        question_id: str,
+        skill_id: str,
+        clarification_type: str,
+    ) -> Dict[str, Any]:
+        return {
+            "event_type": "question_clarification_used",
+            "student_id": str(student_id or ""),
+            "question_id": str(question_id or ""),
+            "skill_id": str(skill_id or ""),
+            "clarification_type": str(clarification_type or "question_rephrase"),
+            "occurred_at": datetime.now(timezone.utc).isoformat(),
+            "evaluation_effect": "none",
+            "quality_signal_only": True,
+        }
+
+
+_MANAGER: Optional[QuestionClarificationManager] = None
+_MANAGER_LOCK = threading.RLock()
+
+
+def get_manager(root_dir: Optional[str | Path] = None) -> QuestionClarificationManager:
+    global _MANAGER
+    with _MANAGER_LOCK:
+        if _MANAGER is None or (
+            root_dir is not None
+            and Path(root_dir).resolve() != _MANAGER.root_dir.resolve()
+        ):
+            _MANAGER = QuestionClarificationManager(root_dir=root_dir)
+        return _MANAGER
+
+
+def clarify_question(question_text: str, skill_id: str = "", **kwargs: Any) -> Dict[str, Any]:
+    return get_manager().clarify_question(
+        question_text=question_text,
+        skill_id=skill_id,
+        **kwargs,
+    )
+
+
+def get_remedial_concept_package(skill_id: str) -> Dict[str, Any]:
+    return get_manager().get_remedial_concept_package(skill_id)
+
+
+def get_symbol(symbol_id: str) -> Dict[str, Any]:
+    return get_manager().get_symbol(symbol_id)
+
+
+def get_concept(concept_id: str) -> Dict[str, Any]:
+    return get_manager().get_concept(concept_id)

strategy_manager.py

@@ -40,9 +40,14 @@ try:
 except Exception:
     SYSTEM_FOLDER = "system"
 
+try:
+    from question_clarification_manager import QuestionClarificationManager
+except Exception:
+    QuestionClarificationManager = None
 
-STRATEGY_MANAGER_VERSION = "strategy_manager_v3_unified_evidence_prescriptive"
-STRATEGY_SCHEMA_VERSION = "strategy_schema_v3"
+
+STRATEGY_MANAGER_VERSION = "strategy_manager_v5_math_concepts_symbols_contract"
+STRATEGY_SCHEMA_VERSION = "strategy_schema_v4"
 
 
 class StrategyManager:
@@ -99,6 +104,10 @@ class StrategyManager:
         self.skills_manager_error = ""
         self._load_skills_manager()
 
+        self.concept_manager = None
+        self.concept_manager_error = ""
+        self._load_concept_manager()
+
         self._ensure_strategy_files()
 
     # =========================================================
@@ -180,6 +189,105 @@ class StrategyManager:
         digest = hashlib.sha1(raw.encode("utf-8")).hexdigest()[:14]
         return f"strategy_{digest}"
 
+
+    # =========================================================
+    # قاموس المفاهيم والرموز
+    # =========================================================
+
+    def _load_concept_manager(self) -> None:
+        if QuestionClarificationManager is None:
+            self.concept_manager = None
+            self.concept_manager_error = (
+                "question_clarification_manager.py غير متاح."
+            )
+            return
+        try:
+            self.concept_manager = QuestionClarificationManager(
+                root_dir=self.root_dir
+            )
+            self.concept_manager_error = ""
+        except Exception as exc:
+            self.concept_manager = None
+            self.concept_manager_error = repr(exc)
+
+    def get_concept_strategy(self, skill_id: str) -> Dict[str, Any]:
+        skill_key = str(skill_id or "").strip()
+        if not skill_key or self.concept_manager is None:
+            return {
+                "enabled": False,
+                "skill_id": skill_key,
+                "concepts": [],
+                "symbols": [],
+                "requirements": {},
+                "error": self.concept_manager_error,
+            }
+
+        package = self.concept_manager.get_remedial_concept_package(skill_key)
+        concepts = package.get("concepts") or []
+        symbols = package.get("symbols") or []
+
+        concept_cards = []
+        for concept in concepts:
+            concept_cards.append(
+                {
+                    "concept_id": concept.get("concept_id"),
+                    "canonical_name_ar": concept.get("canonical_name_ar"),
+                    "name_en": concept.get("name_en"),
+                    "aliases_ar": concept.get("aliases_ar") or [],
+                    "student_explanation_ar": (
+                        concept.get("student_friendly_explanation_ar")
+                        or concept.get("definition_ar")
+                    ),
+                    "common_confusions": concept.get("common_confusions") or [],
+                    "remedial_explanation": (
+                        concept.get("remedial_explanation") or {}
+                    ),
+                    "media_support": concept.get("media_support") or {},
+                }
+            )
+
+        symbol_cards = []
+        for symbol in symbols:
+            symbol_cards.append(
+                {
+                    "symbol_id": symbol.get("symbol_id"),
+                    "display": symbol.get("display"),
+                    "name_ar": symbol.get("name_ar"),
+                    "spoken_ar": symbol.get("spoken_ar"),
+                    "student_definition_ar": (
+                        symbol.get("student_definition_ar")
+                    ),
+                    "common_confusions": (
+                        symbol.get("common_confusions") or []
+                    ),
+                    "examples": symbol.get("examples") or [],
+                    "remedial_explanation": (
+                        symbol.get("remedial_explanation") or {}
+                    ),
+                }
+            )
+
+        return {
+            "enabled": bool(concept_cards or symbol_cards),
+            "skill_id": skill_key,
+            "concepts": concept_cards,
+            "symbols": symbol_cards,
+            "requirements": {
+                "explain_concept_before_procedure": True,
+                "mention_common_aliases": True,
+                "explain_every_symbol_before_first_use": True,
+                "pronounce_symbol_aloud": True,
+                "distinguish_similar_symbols": True,
+                "text_explanation_required": True,
+                "audio_explanation_supported": True,
+                "micro_video_supported": True,
+                "visual_representation_required_when_helpful": True,
+                "concept_check_required": True,
+                "symbol_check_required_when_symbols_exist": True,
+            },
+            "source": "math_concepts_global_and_math_symbols_global",
+        }
+
     # =========================================================
     # القراءة والكتابة والهجرة
     # =========================================================
@@ -810,6 +918,129 @@ class StrategyManager:
     # بناء عقد الاستراتيجية
     # =========================================================
 
+
+    # =========================================================
+    # مستوى المحتوى مقابل عمر الطالب
+    # =========================================================
+
+    def infer_instructional_stage(
+        self,
+        skill_id: Any,
+        skill_context: Optional[Dict[str, Any]] = None,
+        lesson_context: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        """
+        يحدد مستوى المفهوم نفسه، لا عمر الطالب.
+
+        قد يكون الطالب في الصف التاسع، لكنه يعالج مهارة من الروضة.
+        عندها نبسط المفهوم، مع الحفاظ على نبرة محترمة تناسب عمره.
+        """
+        context = skill_context if isinstance(skill_context, dict) else {}
+        lesson = lesson_context if isinstance(lesson_context, dict) else {}
+
+        candidates = [
+            context.get("grade"),
+            context.get("grade_level"),
+            context.get("grade_min"),
+            context.get("expected_grade_min"),
+            context.get("grade_band"),
+            lesson.get("skill_grade"),
+            lesson.get("global_level"),
+            skill_id,
+        ]
+        joined = " ".join(str(item or "") for item in candidates).lower()
+
+        if any(token in joined for token in (
+            "grade_0", "kindergarten", "early_foundation", "-k-", "_k_",
+            "count-to-20", "count_to_20", "cc-count"
+        )):
+            return "early_foundation"
+        if any(token in joined for token in (
+            "grade_1", "grade_2", "grade_3", "early_primary"
+        )):
+            return "early_primary"
+        if any(token in joined for token in (
+            "grade_4", "grade_5", "grade_6", "upper_primary"
+        )):
+            return "upper_primary"
+        if any(token in joined for token in (
+            "grade_7", "grade_8", "grade_9", "middle_school"
+        )):
+            return "middle_school"
+        if any(token in joined for token in (
+            "grade_10", "grade_11", "grade_12", "high_school"
+        )):
+            return "high_school"
+        return "unknown_stage"
+
+    def build_audience_profile(
+        self,
+        student: Dict[str, Any],
+        skill_id: Any,
+        skill_context: Optional[Dict[str, Any]] = None,
+        lesson_context: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        student = student if isinstance(student, dict) else {}
+        chronological_group = self.get_student_age_group(student)
+        instructional_stage = self.infer_instructional_stage(
+            skill_id=skill_id,
+            skill_context=skill_context,
+            lesson_context=lesson_context,
+        )
+
+        is_foundation = instructional_stage in {
+            "early_foundation",
+            "early_primary",
+        }
+        is_young_student = chronological_group in {
+            "young",
+            "early_childhood",
+        }
+
+        if is_foundation and is_young_student:
+            delivery_mode = "child_friendly_concrete"
+            teacher_tone = "دافئ، بسيط، مشجع، ويستخدم كلمات قصيرة"
+            max_sentence_words = 9
+            vocabulary_level = "very_simple"
+            examples_style = "أشياء محسوسة وعدّ بصري وحركة واضحة"
+        elif is_foundation:
+            delivery_mode = "respectful_foundation_repair"
+            teacher_tone = "محترم، مباشر، بسيط، من دون طفولية أو تعقيد"
+            max_sentence_words = 12
+            vocabulary_level = "simple_respectful"
+            examples_style = "تمثيل محسوس سريع ثم ربط بالرمز"
+        else:
+            delivery_mode = "age_aligned_instruction"
+            teacher_tone = "ودود ومباشر"
+            max_sentence_words = 18
+            vocabulary_level = "grade_appropriate"
+            examples_style = "مثال واضح ثم تدريب"
+
+        return {
+            "chronological_age_group": chronological_group,
+            "instructional_stage": instructional_stage,
+            "delivery_mode": delivery_mode,
+            "teacher_tone": teacher_tone,
+            "max_sentence_words": max_sentence_words,
+            "vocabulary_level": vocabulary_level,
+            "examples_style": examples_style,
+            "concrete_first": bool(is_foundation),
+            "one_action_per_sentence": bool(is_foundation),
+            "use_call_and_response": bool(is_foundation),
+            "avoid_abstract_meta_language": True,
+            "avoid_philosophical_filler": True,
+            "avoid_childish_tone_for_older_student": bool(
+                is_foundation and not is_young_student
+            ),
+            "forbidden_phrases": [
+                "ركز على معنى كل خطوة",
+                "قل لنفسك ما الذي تغير ولماذا",
+                "الهدف ليس حفظ الإجابة",
+                "ابن الحل من أول نقطة مفهومة",
+                "هذا دليل مهم على أن الفكرة أصبحت مستقرة",
+            ],
+        }
+
     def choose_strategy(
         self,
         student: Optional[Dict[str, Any]],
@@ -857,9 +1088,16 @@ class StrategyManager:
             }
 
         skill_context = self.get_skill_context(skill_id)
+        concept_strategy = self.get_concept_strategy(skill_id)
         taxonomy_title = self._skill_title(skill_context, gap_skill or lesson_title)
         skill_title = taxonomy_title or gap_skill or lesson_title or "المهارة المستهدفة"
         profile = skill_context.get("diagnostic_profile", {})
+        audience_profile = self.build_audience_profile(
+            student=student if isinstance(student, dict) else {},
+            skill_id=skill_id,
+            skill_context=skill_context,
+            lesson_context=lesson_context,
+        )
 
         selected_error = str(error_type or lesson_context.get("error_type") or "").strip()
         if not selected_error and isinstance(profile, dict):
@@ -911,6 +1149,26 @@ class StrategyManager:
         media_requirements = {
             "required": True,
             "representations": representations,
+            "concept_and_symbol_requirements": (
+                concept_strategy.get("requirements") or {}
+            ),
+            "concept_media_cards": [
+                {
+                    "concept_id": item.get("concept_id"),
+                    "name_ar": item.get("canonical_name_ar"),
+                    "media_support": item.get("media_support") or {},
+                }
+                for item in (concept_strategy.get("concepts") or [])
+            ],
+            "symbol_media_cards": [
+                {
+                    "symbol_id": item.get("symbol_id"),
+                    "display": item.get("display"),
+                    "spoken_ar": item.get("spoken_ar"),
+                    "meaning_ar": item.get("student_definition_ar"),
+                }
+                for item in (concept_strategy.get("symbols") or [])
+            ],
             "dynamic_visual_preferred": any(
                 method in {"misconception_repair", "multiple_representations", "concrete_representational_abstract", "inquiry_science"}
                 for method in methods
@@ -934,7 +1192,8 @@ class StrategyManager:
             "must_include": [
                 "learning_objective", "teaching_method", "worked_example",
                 "guided_practice", "checkpoint_or_closure", "failure_path",
-                "media_requirements",
+                "media_requirements", "concept_explanation",
+                "symbol_explanation_before_first_use",
             ],
             "must_not_include": [
                 "generic_long_lecture", "student_private_data", "model_names",
@@ -945,12 +1204,33 @@ class StrategyManager:
         teaching_strategy = {
             "methods": methods,
             "method_details": method_details,
-            "teacher_tone": age_profile.get("teacher_tone", "ودود ومباشر"),
+            "teacher_tone": audience_profile.get(
+                "teacher_tone",
+                age_profile.get("teacher_tone", "ودود ومباشر"),
+            ),
             "lesson_style": age_profile.get("lesson_style", "شرح ثم مثال ثم تدريب"),
-            "max_teacher_sentence_words": age_profile.get("max_teacher_sentence_words", 18),
+            "max_teacher_sentence_words": audience_profile.get(
+                "max_sentence_words",
+                age_profile.get("max_teacher_sentence_words", 18),
+            ),
+            "vocabulary_level": audience_profile.get("vocabulary_level"),
+            "delivery_mode": audience_profile.get("delivery_mode"),
+            "examples_style": audience_profile.get("examples_style"),
+            "concrete_first": audience_profile.get("concrete_first", False),
+            "one_action_per_sentence": audience_profile.get(
+                "one_action_per_sentence", False
+            ),
+            "avoid_abstract_meta_language": True,
+            "avoid_philosophical_filler": True,
+            "forbidden_phrases": audience_profile.get("forbidden_phrases", []),
             "representations": representations,
             "feedback_rule": "فسّر سبب الخطأ وقدّم الخطوة التالية المناسبة دون وصف الطالب بالضعف.",
             "interaction_rule": "اعرض سؤالًا واحدًا في كل مرة وانتظر إجابة الطالب.",
+            "concept_strategy": concept_strategy,
+            "concept_rule": (
+                "اشرح معنى المفهوم وأسماءه البديلة قبل الإجراء، "
+                "واشرح الرمز ونطقه قبل أول استخدام."
+            ),
         }
 
         remedial_strategy = {
@@ -981,6 +1261,14 @@ class StrategyManager:
         engagement_strategy = {
             "age_group": age_group,
             "age_profile": age_profile,
+            "audience_profile": audience_profile,
+            "chronological_age_group": audience_profile.get(
+                "chronological_age_group"
+            ),
+            "instructional_stage": audience_profile.get(
+                "instructional_stage"
+            ),
+            "delivery_mode": audience_profile.get("delivery_mode"),
             "attention_policy": deepcopy(strategies.get("attention_policy", {})),
             "pomodoro": deepcopy(strategies.get("pomodoro", {})),
         }
@@ -1018,8 +1306,14 @@ class StrategyManager:
             "remedial_strategy": remedial_strategy,
             "assessment_strategy": assessment_strategy,
             "media_strategy": media_requirements,
+            "concept_strategy": concept_strategy,
             "engagement_strategy": engagement_strategy,
             "taxonomy_context": skill_context,
+            "audience_profile": audience_profile,
+            "instructional_stage": audience_profile.get(
+                "instructional_stage"
+            ),
+            "delivery_mode": audience_profile.get("delivery_mode"),
         }
 
         planner_instruction = self.build_planner_instruction(contract)
@@ -1093,6 +1387,7 @@ class StrategyManager:
         remedial = contract.get("remedial_strategy", {})
         assessment = contract.get("assessment_strategy", {})
         media = contract.get("media_strategy", {})
+        concept_strategy = contract.get("concept_strategy", {})
         return f"""
 أنت تؤدي دور مخطط تعليمي داخل منصة Divid Teacher.
 يجب أن تبني الخطة من عقد الاستراتيجية الآتي، ولا يجوز تجاهله أو استبداله بخطة عامة.
@@ -1106,6 +1401,17 @@ class StrategyManager:
 فئة الخطأ: {remedial.get('error_category', '')}
 المحاولة العلاجية: {remedial.get('route', '')}
 
+مفاهيم المهارة ورموزها:
+{json.dumps(concept_strategy, ensure_ascii=False, indent=2)}
+
+قواعد المفاهيم والرموز:
+- ابدأ بمعنى المفهوم قبل الإجراء الحسابي.
+- اذكر الاسم القياسي والأسماء المدرسية البديلة عند الحاجة.
+- اشرح نطق كل رمز ومعناه قبل أول ظهور له.
+- فرّق بصريًا ولفظيًا بين الرموز المتشابهة.
+- اجعل الشرح النصي والصوتي والفيديو مبنيًا على هذه البطاقات.
+- اختم بسؤال تحقق للمفهوم، وللرمز عند وجود رمز.
+
 طرق التدريس الملزمة:
 {self._format_list(teaching.get('methods', []))}
 
@@ -1151,6 +1457,7 @@ class StrategyManager:
         teaching = contract.get("teaching_strategy", {})
         engagement = contract.get("engagement_strategy", {})
         remedial = contract.get("remedial_strategy", {})
+        concept_strategy = contract.get("concept_strategy", {})
         age_profile = engagement.get("age_profile", {})
         return f"""
 أنت تؤدي دور المعلم المباشر داخل منصة Divid Teacher.
@@ -1161,6 +1468,9 @@ class StrategyManager:
 مستوى التدخل: {contract.get('intervention_level', '')}
 فئة الخطأ: {remedial.get('error_category', '')}
 
+قاموس المفاهيم والرموز الملزم:
+{json.dumps(concept_strategy, ensure_ascii=False, indent=2)}
+
 نبرة المعلم:
 {teaching.get('teacher_tone', '')}
 
@@ -1180,6 +1490,10 @@ class StrategyManager:
 - لا تعرض الحل الكامل قبل أن يحاول الطالب في التدريب الموجه.
 - لا تمنح الإتقان ولا تعد الطالب بفتح الوسام؛ القرار لمدير التقدم.
 - استخدم سؤالًا جديدًا عند التحقق، ولا تكرر سؤال التشخيص.
+- لا تستخدم مفهومًا أو رمزًا قبل شرح معناه ونطقه.
+- اذكر الاسم البديل إذا كان المصطلح القياسي غير مألوف للطالب.
+- لا تحول بطاقة المفهوم إلى محاضرة؛ استخدم تعريفًا قصيرًا وتمثيلًا ومثالًا.
+- يجب أن يشرح الفيديو أو الصوت المفهوم والرمز، لا أن يعرضهما كزخرفة.
 """.strip()
 
     # أغلفة التوافق القديمة. الأسماء محفوظة، لكن النص محايد عن اسم النموذج.
@@ -1258,6 +1572,9 @@ class StrategyManager:
             warnings.append("سياسة الإتقان ليست 100 بالمئة.")
         if strategy.get("media_strategy", {}).get("avoid_text_only_slides") is not True:
             warnings.append("لم تُفعّل قاعدة منع الشرائح النصية وحدها.")
+        concept_strategy = strategy.get("concept_strategy", {})
+        if strategy.get("subject") == "math" and not concept_strategy:
+            warnings.append("لم تُرفق استراتيجية المفاهيم والرموز.")
         return {
             "valid": not errors,
             "errors": errors,