Enhance pronunciation rules and scoring system

- Updated pronunciation rules in `pronunciation-rules.md` to clarify the handling of shwa and kubutz sounds, including new examples and scoring rules.
- Modified `index.html` to integrate scoring rules display, allowing teachers to toggle rules on and off.
- Added tests in `test_scoring.py` to verify the functionality of newly implemented scoring rules and their impact on pronunciation scoring.
- Introduced a new script `compare_verbs.py` to check the phonemes of Arabic verbs against the scorer's expectations, ensuring consistency in pronunciation handling.

README.md

@@ -238,6 +238,20 @@ alter table public.calibrations enable row level security;
 
 An applied rule raises only the matching phoneme score to its configured floor; it never lowers a score. The score response includes `calibrated` when a rule changed it, so a flagged result records which rule effect was involved.
 
+### Pronunciation rules
+
+The scorer reads its dialect and Hebrew-speaker rules from the yaml blocks of `static/assets/pronunciation-rules.md` (see `app/rules.py` and `docs/scoring-dialects-plan.md`). The **ניטור** tab lists every rule taken from that document, under **כללי ההגייה מהמסמך**: which realisations of a letter count as correct, how a mistake is judged (exemptions, per-pair margins), and the feedback each rule gives. All are on by default. A teacher can switch one off, which brings back the behaviour from before the document for every student from the next recording on. The switches are loaded into the scorer at startup and refreshed right after a change. Create the private table once (without it the list still shows, all on, and cannot be changed):
+
+```sql
+create table public.scoring_rules (
+  id         text primary key,                 -- a rule of rules.TOGGLES, e.g. dialect_Q, margins, rule_pharyngeal_h
+  active     boolean not null default true,
+  updated_by text not null default '',
+  updated_at timestamptz not null default now()
+);
+alter table public.scoring_rules enable row level security;
+```
+
 ### Levels
 
 The course has levels, each with a planned number of lessons (`LEVELS` in `app/workbook.py`: שלב א and שלב ב, 10 lessons each). Every lesson in `LESSONS` is keyed by its level and number, `(level, lesson)`; one outside the plan stops the app at startup. The path shows each level under its name, and the lessons not written yet as "בקרוב". Level 1's lessons keep their first ids ("1", topics "l1-…") so recorded attempts and saved classes still match; later levels' are "2.1", topics "l2.1-…".

app/archi.py

@@ -117,8 +117,9 @@ def _align(letters: list[str], units: list[str]) -> tuple[dict[int, set[int]], f
     return matched, best
 
 
-def archify_word(ipa_word: str, ar_word: str) -> tuple[str, list[str]]:
-    """One word: its IPA with symbol tokens, and the letters that could not be placed (ambiguous)."""
+def archify_word(ipa_word: str, ar_word: str, off: frozenset[str] = frozenset()) -> tuple[str, list[str]]:
+    """One word: its IPA with symbol tokens, and the letters that could not be placed (ambiguous).
+    Symbols in `off` (switched off by the teacher) are left as the phoneme the phrase writes."""
     phs = ipa_word.split()
     if any(split_token(p)[0] for p in phs):
         return ipa_word, []      # the phrase writes its symbols itself
@@ -127,7 +128,7 @@ def archify_word(ipa_word: str, ar_word: str) -> tuple[str, list[str]]:
     out, unresolved = list(phs), []
     for i, letter in enumerate(letters):
         sym = LETTER_SYMBOL.get(letter)
-        if sym is None:
+        if sym is None or sym in off:
             continue
         hits = matched.get(i, {-1})
         if len(hits) != 1:
@@ -139,21 +140,21 @@ def archify_word(ipa_word: str, ar_word: str) -> tuple[str, list[str]]:
         for k in units[j][1]:
             out[k] = f"{sym}:{phs[k]}"
     # the vowel of a final ة (and ه written for it): a, e and i are all correct (section 6.3 #5)
-    if (out and ar_word.endswith(("ة", "ه")) and "لله" not in ar_word
+    if ("E" not in off and out and ar_word.endswith(("ة", "ه")) and "لله" not in ar_word
             and base(out[-1]) in {"a", "e", "i"} and len(out) > 1):
         out[-1] = f"E:{out[-1]}"
     return " ".join(out), unresolved
 
 
 @lru_cache(maxsize=32768)  # the whole phrase bank (~12k variants) and the verb game's forms
-def archify(ar: str, ipa: str) -> str:
+def archify(ar: str, ipa: str, off: frozenset[str] = frozenset()) -> str:
     """The variant's IPA with each phoneme of a many-ways letter rewritten as its symbol (see the module doc).
 
     A variant whose Arabic and IPA word counts differ is returned as it is."""
     ipa_words, ar_words = ipa.split("|"), ar.split()
     if len(ipa_words) != len(ar_words):
         return ipa
-    return " | ".join(archify_word(w.strip(), a)[0] for w, a in zip(ipa_words, ar_words))
+    return " | ".join(archify_word(w.strip(), a, off)[0] for w, a in zip(ipa_words, ar_words))
 
 
 def unresolved(ar: str, ipa: str) -> list[tuple[str, str]]:

app/auth.py

@@ -60,6 +60,7 @@ import time
 import urllib.error
 import urllib.parse
 import urllib.request
+from datetime import datetime, timezone
 
 log = logging.getLogger("ihki.auth")
 TIMEOUT = 10
@@ -207,14 +208,14 @@ class SupabaseAuth:
         with urllib.request.urlopen(req, timeout=TIMEOUT) as res:
             return json.load(res)
 
-    def _admin(self, path: str, method: str = "GET", body: dict | None = None):
+    def _admin(self, path: str, method: str = "GET", body: dict | None = None, prefer: str = "return=representation"):
         """A call with the secret key, for the teacher's panel. Unlike a student's own progress, a failure is raised."""
         if not self.secret:
             raise AuthUnavailable("SUPABASE_SECRET_KEY is not set")
         req = urllib.request.Request(
             self.url + path, method=method, data=json.dumps(body).encode() if body is not None else None,
             headers={"Authorization": f"Bearer {self.secret}", "apikey": self.secret, "Content-Type": "application/json",
-                     "Prefer": "return=representation", "User-Agent": "ihki/1.0"})
+                     "Prefer": prefer, "User-Agent": "ihki/1.0"})
         try:
             with urllib.request.urlopen(req, timeout=TIMEOUT) as res:
                 return json.loads(res.read() or b"null")
@@ -502,6 +503,17 @@ class SupabaseAuth:
         """Deletes a calibration proposal or rule; returns whether it existed."""
         return bool(self._admin(f"/rest/v1/calibrations?id=eq.{int(calibration_id)}", "DELETE"))
 
+    def scoring_rules(self) -> list[dict]:
+        """The teacher's switches over the rules of pronunciation-rules.md: id, active, updated_by, updated_at.
+        A rule with no row is on."""
+        return self._admin("/rest/v1/scoring_rules?select=*") or []
+
+    def set_scoring_rule(self, rule_id: str, active: bool, by: str) -> None:
+        """Switches one rule on or off (an upsert on its id)."""
+        self._admin("/rest/v1/scoring_rules", "POST", {"id": rule_id, "active": bool(active), "updated_by": by,
+                                                       "updated_at": datetime.now(timezone.utc).isoformat()},
+                    prefer="resolution=merge-duplicates,return=minimal")
+
     def users(self) -> list[dict]:
         """Every account that has signed in: id, email, name (as Google gave it; empty for one who signed in by email)."""
         users: list[dict] = []

app/main.py

@@ -32,7 +32,7 @@ from .auth import AuthUnavailable, ClassConflict, SupabaseAuth, load_auth
 from .phrases import CATEGORIES, GAMES, LESSONS, LEVELS, PHRASES, public_phrases
 from .prompt_tts import ENGINES, PromptTTSUnavailable, hebrew_mp3
 from .reference import References
-from .rules import check_detectable
+from .rules import TOGGLES, check_detectable
 from .scorer import Scorer, decode_audio, load_scorer
 from .speech_evaluation import SpeechEvaluationService
 from .texts import read_line, text_phrases
@@ -143,6 +143,10 @@ CREATE_CALIBRATIONS = ("create table public.calibrations (id bigint generated al
                        "reviewed_by text, reviewed_at timestamptz, created_at timestamptz not null default now()); "
                        "alter table public.calibrations enable row level security;")
 CALIBRATION_STATUSES = frozenset({"draft", "applied", "rejected"})
+# The teacher's switches over the rules of pronunciation-rules.md (rules.TOGGLES): a rule with no row is on.
+CREATE_SCORING_RULES = ("create table public.scoring_rules (id text primary key, active boolean not null default true, "
+                        "updated_by text not null default '', updated_at timestamptz not null default now()); "
+                        "alter table public.scoring_rules enable row level security;")
 # The students the teacher gave the tutor's rank (see auth.py): theirs in every class, so it is kept by email.
 CREATE_TUTORS = ("create table public.tutors (email text primary key, granted_by text not null default '', "
                  "created_at timestamptz not null default now()); alter table public.tutors enable row level security;")
@@ -333,6 +337,11 @@ def create_app(scorer: Scorer | None = None, tts: SawtakTTS | None = None,
                 app.state.scorer.set_calibrations([r for r in rows if not r.get("model") or r.get("model") == MODEL_ID])
             except AuthUnavailable as e:
                 log.warning("calibrations not loaded: %s", e)
+        if app.state.auth and hasattr(app.state.auth, "scoring_rules"):
+            try:
+                reload_scoring_rules(app.state.auth)
+            except AuthUnavailable as e:   # no table yet: every rule stays on
+                log.warning("scoring rule switches not loaded: %s", e)
         yield
 
     app = FastAPI(title="ihki", lifespan=lifespan)
@@ -625,6 +634,47 @@ def create_app(scorer: Scorer | None = None, tts: SawtakTTS | None = None,
         rows = a.calibrations("applied")
         app.state.scorer.set_calibrations([r for r in rows if not r.get("model") or r.get("model") == MODEL_ID])
 
+    def reload_scoring_rules(a: SupabaseAuth) -> None:
+        app.state.scorer.set_disabled(r["id"] for r in a.scoring_rules() if not r.get("active", True))
+
+    def scoring_rules_error(e: AuthUnavailable) -> HTTPException:
+        if "answered 404" in str(e):
+            return HTTPException(503, f"הטבלה scoring_rules לא קיימת. הריצו ב-SQL Editor: {CREATE_SCORING_RULES}")
+        return HTTPException(503, f"כללי ההגייה לא זמינים: {e}")
+
+    @app.get("/api/scoring-rules")
+    def scoring_rules(a: SupabaseAuth = Depends(teacher_only)):
+        """Every rule taken from pronunciation-rules.md, with whether it is on. All are on until a teacher says otherwise.
+        `stored` is False while the table is missing: the list still shows, but cannot be changed."""
+        s: Scorer = app.state.scorer
+        stored, rows = True, {}
+        try:
+            rows = {r["id"]: r for r in a.scoring_rules()}
+        except AuthUnavailable as e:
+            if "answered 404" not in str(e):
+                raise scoring_rules_error(e)
+            stored = False
+        detectable = check_detectable(s.rules, lambda ph: s.vocab.sound_id(ph) is not None, s.vocab.model_id)
+        return {"stored": stored, "create_sql": None if stored else CREATE_SCORING_RULES, "rules": [
+            {"id": t.id, "group": t.group, "section": t.section, "title": t.title, "description": t.description,
+             "active": t.id not in s.disabled,
+             "updated_by": rows.get(t.id, {}).get("updated_by", ""), "updated_at": rows.get(t.id, {}).get("updated_at"),
+             # a section-3 rule this model cannot hear at all (vowel length): switching it changes nothing
+             "detectable": detectable.get(t.id.removeprefix("rule_"), {}).get("detectable", True)}
+            for t in TOGGLES]}
+
+    @app.put("/api/scoring-rules/{rule_id}")
+    def switch_scoring_rule(rule_id: str, body: dict = Body(...), a: SupabaseAuth = Depends(teacher_only),
+                            user: dict | None = Depends(signed_in)):
+        if rule_id not in {t.id for t in TOGGLES} or not isinstance(body.get("active"), bool):
+            raise HTTPException(400, "unknown rule or invalid switch")
+        try:
+            a.set_scoring_rule(rule_id, body["active"], user["email"].lower())
+            reload_scoring_rules(a)
+        except AuthUnavailable as e:
+            raise scoring_rules_error(e)
+        return {"ok": True, "disabled": sorted(app.state.scorer.disabled)}
+
     @app.get("/api/calibrations")
     def calibration_proposals(a: SupabaseAuth = Depends(teacher_only)):
         try:

app/rules.py

@@ -55,6 +55,10 @@ class Rules:
     titles: dict[str, str]                       # rule id -> title
     heard_labels: dict[str, str]
     margins: dict[tuple[str, str], float] = field(default_factory=dict)
+    # a vowel heard between two consonants of a word (3.10): rule, severity, min_peak, min_frames, score_cap, feedback
+    insertion: dict | None = None
+    # short vowels a rule flags although short vowels are not flagged (6.3 #7): vowel -> rule id (3.11: u)
+    flag_vowels: dict[str, str] = field(default_factory=dict)
 
     def members(self, symbol: str, written: str | None = None) -> list[str]:
         """The correct realisations of an abstract symbol, in base() names, first the dialects' own.
@@ -123,7 +127,13 @@ def parse(text: str) -> Rules:
     archi, dialects, optional, scoring, labels = {}, ["urban", "rural"], False, {}, {}
     checks: dict[tuple[str, str], Check] = {}
     titles: dict[str, str] = {}
+    insertion, flag_vowels = None, {}
     for doc in _blocks(text):
+        if "insertion" in doc:
+            titles[doc["id"]] = doc.get("title", doc["id"])
+            insertion = {"rule": doc["id"], **doc["insertion"]}
+        for v in doc.get("flag_vowels", []):
+            flag_vowels[str(v)] = doc["id"]
         if "archiphonemes" in doc:
             archi = {k: {d: list(v.get(d, [])) for d in ("urban", "rural", "also_ok", "optional")}
                      for k, v in doc["archiphonemes"].items()}
@@ -140,7 +150,7 @@ def parse(text: str) -> Rules:
                     key = (norm(str(c["target"])), norm(str(heard)))
                     # two spellings of one sound (ʁ and ɣ) meet here: the first rule written wins
                     checks.setdefault(key, Check(doc["id"], key[0], key[1], int(c["severity"]), str(c["feedback"])))
-    rules = Rules(archi, dialects, optional, scoring, checks, titles, labels)
+    rules = Rules(archi, dialects, optional, scoring, checks, titles, labels, insertion=insertion, flag_vowels=flag_vowels)
     for m in scoring.get("margins", []):
         # base() drops vowel length, so a margin for long vowels would land on quality pairs (a / i) it was not meant for
         for t in (t for t in m["target"] if "ː" not in str(t)):
@@ -235,3 +245,87 @@ EXEMPTIONS = [
     ("article_vowel_elided", _article_vowel_elided, None),
     ("near_vowel", _near_vowel, "near_vowel_floor"),
 ]
+
+
+# ---------- the rules a teacher can switch off (ניטור): every behaviour taken from pronunciation-rules.md ----------
+
+@dataclass(frozen=True)
+class Toggle:
+    id: str
+    group: str        # "accept": what counts as correct · "judge": how a mistake is judged · "feedback": what is said
+    section: str      # where pronunciation-rules.md has it
+    title: str
+    description: str  # what the scorer does while the rule is on; off is the behaviour before the document
+
+
+def _toggles() -> list[Toggle]:
+    letters = [
+        ("Q", "ق", "ʔ (עירוני), k (כפרי) או q", "אַהְוֶה, כַּהְוֶה וקַהְוֶה נכונות שלושתן."),
+        ("K", "ك", "k או tʃ (כפרי)", "כַּלְבּ וצ'ַלְבּ נכונות שתיהן."),
+        ("TH", "ث", "t או θ (כפרי), ו־s במילים ספרותיות כשהמשפט כותב s", "תְלַאתֶה ות'לַאת'ֶה נכונות שתיהן."),
+        ("DH", "ذ", "d או ð (כפרי), ו־z במילים ספרותיות כשהמשפט כותב z", "דַהַבּ וד״ַהַבּ נכונות שתיהן."),
+        ("ZH", "ظ", "dˤ, zˤ או ðˤ", "ד'ֻהְר וט'ֻהְר נכונות שתיהן."),
+        ("J", "ج", "dʒ או ʒ", "ג' כמו בג'ינס או ז' כמו בז'קט."),
+    ]
+    out = [Toggle(f"dialect_{s}", "accept", "5", f"{ar}: {said}",
+                  f"כל המימושים נכונים, וההגה נמדד מול סכום ההסתברויות שלהם (6.1). {ex} "
+                  f"כבוי: נבדק רק המימוש שכתוב במשפט.") for s, ar, said, ex in letters]
+    out += [
+        Toggle("final_vowel", "accept", "6.3 #5", "תנועה סופית של ة: a, e או i",
+               "אַהְוֶה, אַהְוַה ואַהְוִי נכונות. כבוי: נבדקת התנועה שכתובה במשפט."),
+        Toggle("diphthong", "accept", "6.3 #8", "eː גם כ־aj, ו־oː גם כ־aw",
+               "בֵּית ובַּיְת נכונות שתיהן (נבדק כווריאנט נוסף). כבוי: רק התנועה הארוכה."),
+        Toggle("glottal_dropped", "judge", "6.3 #1–2", "עצירה סותמית שהושמטה אינה טעות",
+               "ʔ (ء, ו־ق עירונית) שלא נשמעה מקבלת ציון מלא, כמו אצל דוברים ילידיים (אַנַא ← אנה)."),
+        Toggle("article_vowel_elided", "judge", "6.3 #3", "תנועת ה־ال אחרי תנועה",
+               "ה־i של ال שלא נאמרה אחרי מילה שמסתיימת בתנועה (עַלַא לְ...) אינה טעות."),
+        Toggle("near_vowel", "judge", "6.3 #7", "תנועות קר��בות",
+               "תנועה שנשמעה כשכנתה (i/e, u/o, a/e) או באורך אחר מקבלת לפחות 90."),
+        Toggle("margins", "judge", "6.2", "מרווח ביטחון לזוגות שהמודל מבלבל",
+               "עיצור מודגש נחשב שגוי רק אם הרגיל סביר ממנו פי 2 בערך, ħ מול h פי 1.5, "
+               "ו־h נחשבת שנבלעה רק אם היא חלשה פי 2 מסף ההשמטה. "
+               "כבוי: כל מתחרה שמנצח מסמן טעות."),
+        Toggle("unnamed_sounds", "judge", "7", "צליל שאינו בערבית או בעברית לא נקרא בשמו",
+               "כשהמודל הרב־לשוני שומע צליל זר (נקישה, צליל רטרופלקסי) הוא מדווח כ'לא ברור'. כבוי: נאמר שם הסמל."),
+        Toggle("tips_by_severity", "feedback", "6.2", "סדר הטיפים לפי חומרה, עד 3",
+               "טעות שמשנה משמעות (ח, ע) מוצגת לפני מבטא, ואחריה הציון הנמוך. כבוי: לפי הציון בלבד, עד 4."),
+    ]
+    own = {
+        "cluster": "תנועה שהמודל שומע בבירור בין שני עיצורים של אותה מילה (katiir במקום ktiir) מורידה את העיצור השני "
+                   "לכל היותר ל־60, עם טיפ בחומרה 1. לא בצרור שפותח את המשפט, ולא ליד w או j. כבוי: תנועה שנוספה לא נבדקת.",
+        "kubutz": "u אחרי עיצור היא התנועה הקצרה היחידה שמסומנת: כשנשמטה, או נשמעה כ־e, i או שווא. "
+                  "כ־o היא עדיין תנועה קרובה. כבוי: כמו שאר התנועות הקצרות, לא מסומנת.",
+    }
+    for rule_id, title, section in (("pharyngeal_h", "ח לועית", "3.1"), ("ayin", "ע לועית", "3.2"),
+                                    ("emphatics", "עיצורים מודגשים", "3.3"), ("r_tap", "ר מתגלגלת", "3.4"),
+                                    ("ghain", "ע' היא ה־ר העברית", "3.5"), ("h", "ה נהגית תמיד", "3.6"),
+                                    ("w", "ו היא w", "3.7"), ("b", "ב היא תמיד b", "3.7"), ("f", "פ היא תמיד f", "3.7"),
+                                    ("vowel_length", "תנועה ארוכה", "3.8"), ("jim", "ג' ולא g", "3.9"),
+                                    ("cluster", "שני עיצורים צמודים", "3.10"), ("kubutz", "קובוץ ברור", "3.11")):
+        out.append(Toggle(f"rule_{rule_id}", "judge" if rule_id in own else "feedback", section, title,
+                          own.get(rule_id) or
+                          f"הטיפ והחומרה (בסוגריים) מהמסמך כשנשמע: {_confusions(rule_id)}. "
+                          "כבוי: טיפ כללי בחומרה בינונית; ההחלטה אם לסמן לא משתנה."))
+    return out
+
+
+def _confusions(rule_id: str) -> str:
+    """'ח ← ח עברית (3), ה (2), נבלעת (2)': the substitutions a section-3 rule speaks for, in Hebrew labels."""
+    rules = load()
+    by_target: dict[str, list[str]] = {}
+    for c in rules.checks.values():
+        if c.rule == rule_id:
+            heard = rules.label(c.heard) or c.heard
+            item = f"{'נבלעת' if c.heard == '_' else heard} ({c.severity})"
+            if item not in by_target.setdefault(c.target, []):
+                by_target[c.target].append(item)
+    return "; ".join(f"{_LETTER.get(t, t)} ← {', '.join(items)}" for t, items in by_target.items())
+
+
+# a target sound by the letter of the transliteration (section 1), for the teacher's list
+_LETTER = {"ħ": "ח", "ʕ": "ע", "sˤ": "צ", "tˤ": "ט", "dˤ": "ד'", "ZH": "ט'", "r": "ר", "ɣ": "ע'", "h": "ה", "w": "ו",
+           "b": "ב", "f": "פ", "J": "ג'", "a": "אַא", "i": "ִי", "u": "וּ", "e": "ֵי", "o": "וֹ"}
+
+
+TOGGLES = _toggles()
+TOGGLE_IDS = frozenset(t.id for t in TOGGLES)

app/scorer.py

@@ -14,7 +14,7 @@ import numpy as np
 from .align import Alignment, GopConfig, TokenScore, ctc_viterbi, edit_distance, greedy_decode, score_tokens
 from .archi import archify, diphthong_variants, split_token, written
 from .phones import base
-from .rules import EXEMPTIONS, Rules, elided_article, near_vowels, load as load_rules  # noqa: F401 (re-exported)
+from .rules import EXEMPTIONS, TOGGLE_IDS, Check, Rules, elided_article, near_vowels, load as load_rules  # noqa: F401 (re-exported)
 from .tips import VOWELS, letter_reason, sound_name, tip_for
 from .translit import CONSONANTS as _HEB_C, HEARD_ONLY as _HEB_HEARD, VOWELS as _HEB_V, to_hebrew, word_letters, word_to_hebrew
 
@@ -220,6 +220,8 @@ class Fit:
     candidates: list[tuple[str, str, float | None]] = field(default_factory=list)  # (ar, ipa, path log-prob)
     gop_scores: list[TokenScore] = field(default_factory=list)   # before the exemptions
     exempted: list[str | None] = field(default_factory=list)     # per token, the exemption that applied
+    exempt_scores: list[TokenScore] = field(default_factory=list)  # after the exemptions, before the inserted vowels
+    inserted: dict[int, str] = field(default_factory=dict)        # token -> the vowel heard before it (rules 3.10)
     distance: int = 0        # edit distance of the greedy decode from the chosen variant
 
 
@@ -233,6 +235,59 @@ class Scorer:
         names = (set(HEBREW_SOUNDS) | self.rules.interference() | set(self.rules.heard_labels)
                  | {p for s in self.rules.archiphonemes for p in self.rules.members(s)})
         self.named = {i for i in (vocab.sound_id(n) for n in names) if i is not None}
+        self.disabled: frozenset[str] = frozenset()  # rules.TOGGLES the teacher switched off (ניטור)
+
+    def set_disabled(self, ids) -> None:
+        """Atomically replaces the switched-off rules; unknown ids are ignored."""
+        self.disabled = frozenset(ids) & TOGGLE_IDS
+
+    def _on(self, toggle: str) -> bool:
+        return toggle not in self.disabled
+
+    def _off_symbols(self) -> frozenset[str]:
+        """The archi.py symbols not to use: letters whose dialect rule is off, and E for the final-vowel rule."""
+        off = {t.removeprefix("dialect_") for t in self.disabled if t.startswith("dialect_")}
+        return frozenset(off | ({"E"} if "final_vowel" in self.disabled else set()))
+
+    def _check(self, tok: TargetToken, heard: str | None):
+        """The rule of pronunciation-rules.md for this substitution, unless the teacher switched it off.
+        A rule for a short vowel (3.11: u) speaks for that vowel only, not for its long form (base() drops length)."""
+        check = self.rules.check([tok.sound, tok.phoneme], heard)
+        if check and check.target in self.rules.flag_vowels and tok.phoneme != check.target:
+            return None
+        return check if check and self._on(f"rule_{check.rule}") else None
+
+    def _flag_vowel(self, toks: list[TargetToken], i: int) -> bool:
+        """Is token i a short vowel a rule flags (3.11: u after a consonant of the same word, not the و of 'and')?"""
+        t = toks[i]
+        rule = self.rules.flag_vowels.get(t.phoneme)
+        return bool(rule and self._on(f"rule_{rule}") and i > 0 and toks[i - 1].word == t.word
+                    and toks[i - 1].phoneme not in VOWELS)
+
+    _GLIDES = {"w", "j"}  # the way into or out of a glide sounds like a vowel in anyone's speech
+
+    def _insertions(self, logp: np.ndarray, toks: list[TargetToken], al: Alignment) -> dict[int, str]:
+        """Rules 3.10: token -> the vowel the model clearly heard between it and the consonant before it, in one word
+        (katiir for ktiir). The cluster that opens the sentence is spared (6.3 #16), and so are pairs with w or j."""
+        spec = self.rules.insertion
+        if not spec or not self._on(f"rule_{spec['rule']}"):
+            return {}
+        vowels = {i: base(self.vocab.i2t[i]) for i in (self.vocab.sound_id(v) for v in ("a", "e", "i", "o", "u", "ə"))
+                  if i is not None}
+        real = logp[:, :self.vocab.n_real]
+        greedy = real.argmax(1)
+        min_peak, min_frames = float(np.log(spec.get("min_peak", 0.5))), int(spec.get("min_frames", 2))
+        out: dict[int, str] = {}
+        for j in range(2, len(toks)):     # j == 1 is the cluster that opens the sentence
+            a, b = toks[j - 1], toks[j]
+            if (a.word != b.word or a.phoneme in VOWELS or b.phoneme in VOWELS
+                    or {base(a.phoneme), base(b.phoneme)} & self._GLIDES):
+                continue
+            frames = [t for t in range(al.spans[j - 1][0], al.spans[j][1])
+                      if int(greedy[t]) in vowels and real[t, greedy[t]] >= min_peak]
+            if len(frames) >= min_frames:
+                out[j] = vowels[int(greedy[frames[0]])]
+        return out
 
     def set_calibrations(self, rows: list[dict]) -> None:
         """Atomically replaces applied score floors. A blank phrase is a global rule."""
@@ -352,10 +407,11 @@ class Scorer:
         """(arabic, ipa, ipa with symbols, tokens) for each accepted variant and its diphthong forms. Variants
         that differ only in how a many-ways letter is said (ʔ / q / k for ق) become one: the first written.
         A diphthong form the model has no symbols for is left out."""
-        out, seen = [], set()
+        out, seen, off = [], set(), self._off_symbols()
         for ar, ipa in phrase["variants"]:
-            for n, form in enumerate((ipa, *diphthong_variants(ar, ipa))):
-                aipa = archify(ar, form)
+            forms = (ipa, *diphthong_variants(ar, ipa)) if self._on("diphthong") else (ipa,)
+            for n, form in enumerate(forms):
+                aipa = archify(ar, form, off)
                 if aipa in seen:
                     continue
                 seen.add(aipa)
@@ -386,19 +442,25 @@ class Scorer:
         ids = [t.id for t in toks]
         ar_words = ar.split()
         scores = score_tokens(ext, al, ids, blank, self.cfg.gop, [vocab.members.get(i) for i in ids],
-                              vocab.n_real, self.named)
+                              vocab.n_real, self.named if self._on("unnamed_sounds") else None)
         gop_scores, exempted = list(scores), [None] * len(scores)
         for i, (t, sc) in enumerate(zip(toks, scores)):
             heard = vocab.i2t.get(sc.competitor) if sc.competitor is not None else None
             for name, applies, floor in EXEMPTIONS:
-                if applies(toks, i, sc, heard, ar_words):
+                if self._on(name) and applies(toks, i, sc, heard, ar_words):
                     scores[i] = replace(sc, score=max(sc.score, 100.0 if floor is None else getattr(self.cfg, floor)))
                     exempted[i] = name
                     break
+        exempt_scores = list(scores)
+        inserted = self._insertions(logp, toks, al)
+        cap = float((self.rules.insertion or {}).get("score_cap", 60))
+        for j in inserted:
+            scores[j] = replace(scores[j], score=min(scores[j].score, cap))
         same = lambda h, t: h == t or h in vocab.members.get(t, ())
         distance = edit_distance(heard_ids, ids, same)
         unrelated = bool(distance / max(1, len(ids)) > self.cfg.unrelated_ratio)
-        return Fit(ar, ipa, aipa, toks, al, scores, heard_ids, unrelated, ext, tried, gop_scores, exempted, distance)
+        return Fit(ar, ipa, aipa, toks, al, scores, heard_ids, unrelated, ext, candidates=tried, gop_scores=gop_scores,
+                   exempted=exempted, exempt_scores=exempt_scores, inserted=inserted, distance=distance)
 
     def _heatmap(self, logp: np.ndarray, toks: list[TargetToken], alignment, scores,
                  duration_s: float | None) -> dict:
@@ -438,15 +500,25 @@ class Scorer:
                 "frames": frames, "frame_bins": bins, "rows": rows,
                 "tracks": {"expected": expected, "heard": heard}}
 
+    def _max_tips(self) -> int:
+        """As many tips as the rules document says (3), or the 4 of before when its severity order is off."""
+        if self.cfg.max_tips:
+            return self.cfg.max_tips
+        return int(self.rules.scoring.get("max_tips", 4)) if self._on("tips_by_severity") else 4
+
     def _beyond_margin(self, tok: TargetToken, sc: TokenScore, heard: str | None) -> bool:
         """Is the competitor likelier than the target by more than the pair's margin? Pairs the model confuses
         on natives too (emphatics, a dropped h) need a clearer win before they count as a mistake."""
         targets = [tok.sound, tok.phoneme]
         if sc.deleted:
-            return sc.peak <= self.cfg.gop.deleted_peak - self.rules.margin(targets, "_")
+            return sc.peak <= self.cfg.gop.deleted_peak - self._margin(targets, "_")
         if heard is None:
             return True
-        return -sc.gop >= self.rules.margin(targets, heard)
+        return -sc.gop >= self._margin(targets, heard)
+
+    def _margin(self, targets: list[str], heard: str | None) -> float:
+        """The pair's margin (rules 6.2), or the default for every pair when the teacher switched margins off."""
+        return self.rules.margin(targets if self._on("margins") else [], heard)
 
     def _dialect(self, toks: list[TargetToken], scores: list[TokenScore]) -> dict:
         """Which dialect the accepted realisations point to: {"dialect": urban | rural} when they agree,
@@ -502,13 +574,21 @@ class Scorer:
         tr_words = to_hebrew(ipa, ar)
         for idx, (tok, sc) in enumerate(zip(toks, scores)):
             heard_ph = "_" if sc.deleted else (i2t.get(sc.competitor) if sc.competitor is not None else None)
-            check = self.rules.check([tok.sound, tok.phoneme], heard_ph)
+            check = self._check(tok, heard_ph)
             beyond.append(self._beyond_margin(tok, sc, heard_ph))
-            flagged = bool(sc.score < self.cfg.flag_below) and tok.phoneme not in VOWELS and beyond[-1]
-            heard_as.append(heard_ph)
-            checks.append(check)
+            flagged = (bool(sc.score < self.cfg.flag_below) and beyond[-1]
+                       and (tok.phoneme not in VOWELS or self._flag_vowel(toks, idx)))
+            if idx in fit.inserted:   # a vowel before this consonant (3.10): the reason its letter gives
+                spec = self.rules.insertion
+                heard_as.append("+" + fit.inserted[idx])
+                checks.append(Check(spec["rule"], tok.phoneme, "+", int(spec["severity"]), str(spec["feedback"])))
+            else:
+                heard_as.append(heard_ph)
+                checks.append(check)
             p = {"ipa": tok.phoneme, "word": tok.word, "score": sc.score,
                  "flagged": flagged, "heard": heard_ph if flagged else None}
+            if idx in fit.inserted:
+                p["inserted"] = fit.inserted[idx]
             if tok.sound != tok.phoneme:
                 p["sound"] = tok.sound
             if sc.realised is not None:
@@ -523,6 +603,13 @@ class Scorer:
                     tip["idx"] = idx
                     tip["score"] = round(sc.score)
                     tips.append(tip)
+            if idx in fit.inserted and not unrelated and "cluster" not in seen:
+                seen.add("cluster")
+                spec = self.rules.insertion
+                tips.append({"title": self.rules.titles.get(spec["rule"], spec["rule"]), "text": str(spec["feedback"]),
+                             "key": spec["rule"], "severity": int(spec["severity"]),
+                             "word": ar_words[tok.word] if tok.word < len(ar_words) else "",
+                             "word_tr": tr_words[tok.word], "idx": idx, "score": round(sc.score)})
 
         n_words = len(ipa.split("|"))
         heard_words = self._heard_hebrew(logp, toks, al, fit.aipa, ar_words)
@@ -553,8 +640,9 @@ class Scorer:
         if unrelated:
             overall = min(overall, 30.0)
         # most crucial first: the mistakes that change meaning (severity 3), then the worst-scoring sounds
-        max_tips = self.cfg.max_tips or int(self.rules.scoring.get("max_tips", 4))
-        tips = sorted(tips, key=lambda t: (-t["severity"], t["score"]))[:max_tips]
+        max_tips = self._max_tips()
+        tips = (sorted(tips, key=lambda t: (-t["severity"], t["score"])) if self._on("tips_by_severity")
+                else sorted(tips, key=lambda t: t["score"]))[:max_tips]
         tip_idx, issue_idx = {t["idx"] for t in tips}, []
 
         # Anything short of 100 must say why: every imprecise sound that did not get a full tip,
@@ -571,6 +659,11 @@ class Scorer:
             for i in issue_idx:
                 tok, sc = toks[i], scores[i]
                 comp = i2t.get(sc.competitor) if sc.competitor is not None else None
+                if i in fit.inserted:
+                    issues.append({"sound": "תנועה מיותרת לפני " + (sound_name(tok.phoneme) or tok.phoneme),
+                                   "word_tr": tr_words[tok.word], "score": round(sc.score), "missing": False,
+                                   "heard": sound_name(fit.inserted[i])})
+                    continue
                 issues.append({"sound": sound_name(tok.sound) or sound_name(tok.phoneme) or tok.phoneme,
                                "word_tr": tr_words[tok.word], "score": round(sc.score), "missing": bool(sc.deleted),
                                "heard": None if sc.deleted else sound_name(comp)})
@@ -594,7 +687,7 @@ class Scorer:
         (the 'stages' part of the phoneme analysis). Nothing here changes the result."""
         cfg, g, i2t = self.cfg, self.cfg.gop, self.vocab.i2t
         p = lambda lp: round(float(np.exp(lp)), 4) if lp > -1e20 else 0.0
-        max_tips = cfg.max_tips or int(self.rules.scoring.get("max_tips", 4))
+        max_tips = self._max_tips()
         n = len(fit.toks)
         tokens = []
         for i, (tok, gsc, sc) in enumerate(zip(fit.toks, fit.gop_scores, scores)):
@@ -606,7 +699,8 @@ class Scorer:
             b = bases[i]
             stages = [
                 {"stage": "gop", "score": gsc.score},
-                {"stage": "exemption", "score": fit.scores[i].score, "applied": fit.exempted[i]},
+                {"stage": "exemption", "score": fit.exempt_scores[i].score, "applied": fit.exempted[i]},
+                {"stage": "insertion", "score": fit.scores[i].score, "applied": fit.inserted.get(i)},
                 {"stage": "baseline", "score": after_baseline[i].score, "ref": b,
                  "applied": b is not None and b < 100},
                 {"stage": "calibration", "score": sc.score, "floor": floors[i],
@@ -623,7 +717,7 @@ class Scorer:
                 "gop_factor": round(float(np.exp(gsc.gop * g.leniency)), 3),
                 "confidence_factor": round(float(np.sqrt(confidence)), 3),
                 "deleted": gsc.deleted, "stages": stages, "final": sc.score,
-                "margin": {"needed": self.rules.margin(targets, "_" if gsc.deleted else heard_ph),
+                "margin": {"needed": self._margin(targets, "_" if gsc.deleted else heard_ph),
                            "got": (round(g.deleted_peak - gsc.peak, 3) if gsc.deleted else round(-gsc.gop, 3)),
                            "beyond": beyond[i]},
                 "vowel": tok.phoneme in VOWELS, "weight": 0.5 if tok.phoneme in VOWELS else 1.0,
@@ -641,8 +735,12 @@ class Scorer:
                 "word_min_weight": cfg.word_min_weight, "vowel_weight": 0.5, "unrelated_ratio": cfg.unrelated_ratio,
                 "unrelated_cap": 30.0, "letter_good": LETTER_GOOD, "max_tips": max_tips, "max_issues": cfg.max_issues,
                 "ref_min_mean": cfg.ref_min_mean, "margin_default": float(self.rules.scoring.get("margin_default", 0.0)),
-                "margins": [{"target": t, "heard": h, "margin": m} for (t, h), m in sorted(self.rules.margins.items())],
-                "exemptions": [name for name, _, _ in EXEMPTIONS],
+                "margins": [{"target": t, "heard": h, "margin": m} for (t, h), m in sorted(self.rules.margins.items())]
+                if self._on("margins") else [],
+                "exemptions": [name for name, _, _ in EXEMPTIONS if self._on(name)],
+                "insertion": ({k: self.rules.insertion[k] for k in ("score_cap", "min_peak", "min_frames")}
+                              if self.rules.insertion and self._on(f"rule_{self.rules.insertion['rule']}") else None),
+                "disabled": sorted(self.disabled),
             },
             "variants": [{"ar": ar, "ipa": ipa, "logp": lp, "chosen": ar == fit.ar and ipa == fit.ipa}
                          for ar, ipa, lp in fit.candidates],

app/tips.py

@@ -84,7 +84,9 @@ def letter_reason(expected: str, heard: str | None, check=None) -> dict:
     name = sound_name(expected) or expected
     heard = HEARD_ALIASES.get(heard, heard)
     other = sound_name(heard)
-    if heard == "_":
+    if heard and heard.startswith("+"):   # a vowel added before this consonant (rules 3.10)
+        why = f"נוספה {sound_name(heard[1:]) or 'תנועה'} לפני {name}"
+    elif heard == "_":
         why = f"{name} לא נשמעה"
     elif other and other != name:
         why = f"{name} נשמעה כמו {other}"
@@ -104,7 +106,7 @@ def tip_for(expected: str, heard: str | None, check=None) -> dict | None:
 
     `check` (rules.Check) is the rule of pronunciation-rules.md for this substitution: its feedback and
     severity win over TIPS. The key stays "expected>heard" either way."""
-    if expected in VOWELS:
+    if expected in VOWELS and not check:   # a short vowel gets a tip only from a rule that flags it (3.11)
         return None
     heard = HEARD_ALIASES.get(heard, heard) if heard else "_"
     if heard == "_" and expected in NO_DELETION_TIP:

scripts/compare_verbs.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""Check the phonemes of static/assets/arabic_verbs.json against what the scorer uses.
+
+Usage:  python scripts/compare_verbs.py              # summary + every difference
+        python scripts/compare_verbs.py --all        # also list the forms that match
+        python scripts/compare_verbs.py --no-vocab   # skip the model-vocab check (no tokenizer download)
+
+For every past / future form (and its accepted_phonemes) it reports:
+  bank     the same Arabic word in the phrase bank (phrases.py, workbook LEX, grammar VERBS) and whether its IPA
+           agrees: "same" (identical), "same sounds" (identical once archify() symbols and base() are applied,
+           i.e. the scorer would build the same target), or "differs"
+  archi    how archify() rewrites the form (ق ك ث ذ ظ ج as Q K TH DH ZH J) and the letters it could not place
+  vocab    phonemes the model has no symbol for (mapped to a fallback, or not expressible at all)
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from collections import Counter
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT))
+
+from app.archi import archify, split_token, unresolved  # noqa: E402
+from app.grammar import VERBS  # noqa: E402
+from app.phones import base  # noqa: E402
+from app.phrases import PHRASES  # noqa: E402
+from app.workbook import LEX  # noqa: E402
+
+VERBS_JSON = ROOT / "static/assets/arabic_verbs.json"
+_MARKS = re.compile(r"[ً-ْٰـ]")  # harakat, shadda, sukun, dagger alif, tatweel
+
+
+def loose(ar: str) -> str:
+    """Arabic without diacritics and with the hamza seats of alif folded, for a lookup that tolerates spelling."""
+    return _MARKS.sub("", ar).translate(str.maketrans("أإآ", "ااا")).replace("ى", "ي")
+
+
+def bank_words() -> dict[str, set[str]]:
+    """Arabic word -> every IPA the bank gives it (single words of each variant, LEX, grammar VERBS)."""
+    out: dict[str, set[str]] = {}
+    for p in PHRASES:
+        for ar, ipa in p["variants"]:
+            ars, ipas = ar.split(), [w.strip() for w in ipa.split("|")]
+            if len(ars) == len(ipas):
+                for a, i in zip(ars, ipas):
+                    out.setdefault(a, set()).add(i)
+    for key, (_tr, ipas) in LEX.items():
+        out.setdefault(key.partition("#")[0], set()).update(ipas)
+    for forms in VERBS.values():
+        for _he, _tr, ar, ipas in forms:
+            out.setdefault(ar, set()).update(ipas)
+    return out
+
+
+def sounds(ar: str, ipa: str) -> tuple[str, ...]:
+    """The target as the scorer sees it: archify() symbols kept, other phonemes reduced to their base() sound."""
+    out = []
+    for tok in archify(ar, ipa).split():
+        if tok == "|":
+            continue
+        sym, _members, ph = split_token(tok)
+        out.append(sym if sym else base(ph))
+    return tuple(out)
+
+
+def load_vocab():
+    from huggingface_hub import hf_hub_download
+
+    from app.scorer import Vocab
+    model_id = os.environ.get("MODEL_ID", "facebook/wav2vec2-xlsr-53-espeak-cv-ft")
+    path = Path(model_id) / "vocab.json" if Path(model_id).is_dir() else hf_hub_download(model_id, "vocab.json")
+    return Vocab(json.loads(Path(path).read_text(encoding="utf-8")))
+
+
+def vocab_issues(vocab, ar: str, ipa: str) -> list[str]:
+    issues = []
+    for tok in archify(ar, ipa).split():
+        before = dict(vocab.downgraded)
+        try:
+            vocab.token(tok)
+        except KeyError as e:
+            issues.append(f"{tok}: {e}")
+            continue
+        issues += [f"{k}->{v}" for k, v in vocab.downgraded.items() if before.get(k) != v]
+    return issues
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--all", action="store_true", help="also print forms that match the bank")
+    ap.add_argument("--no-vocab", action="store_true", help="skip the model-vocab check")
+    args = ap.parse_args()
+
+    data = json.loads(VERBS_JSON.read_text(encoding="utf-8"))
+    bank = bank_words()
+    bank_loose: dict[str, set[str]] = {}
+    for a, ipas in bank.items():
+        bank_loose.setdefault(loose(a), set()).update(ipas)
+    vocab = None if args.no_vocab else load_vocab()
+
+    tally: Counter[str] = Counter()
+    symbols: Counter[str] = Counter()
+    for section, entry in data.items():
+        for verb in entry["verbs"]:
+            for tense in ("past", "future"):
+                form = verb[tense]
+                ar = form["arabic"]
+                for ipa in [form["phonemes"], *form.get("accepted_phonemes", [])]:
+                    lines = []
+                    for tok in ipa.split():
+                        if split_token(tok)[0]:
+                            symbols[tok] += 1
+                    known = bank.get(ar) or bank_loose.get(loose(ar))
+                    if not known:
+                        status = "not in bank"
+                    elif ipa in known:
+                        status = "same"
+                    elif sounds(ar, ipa) in {sounds(ar, k) for k in known}:
+                        status = "same sounds"
+                    else:
+                        status = "differs"
+                        how = "" if ar in bank else " (matched without diacritics: may be another word)"
+                        lines.append(f"    bank:  {' / '.join(sorted(known))}{how}")
+                    tally[status] += 1
+                    arch = archify(ar, ipa)
+                    if arch != ipa:
+                        lines.append(f"    archi: {arch}")
+                    if missing := unresolved(ar, ipa):
+                        tally["unresolved"] += 1
+                        lines.append(f"    unresolved letters: {' '.join(l for _, l in missing)}")
+                    if vocab is not None and (bad := vocab_issues(vocab, ar, ipa)):
+                        tally["vocab"] += 1
+                        lines.append(f"    vocab: {', '.join(bad)}")
+                    if status in ("differs",) or missing or args.all or (vocab is not None and bad):
+                        print(f"[{section}] {verb['hebrew']} {tense} {ar}  {ipa}  -> {status}")
+                        print("\n".join(lines)) if lines else None
+
+    print("\n== summary ==")
+    for k in ("same", "same sounds", "differs", "not in bank", "unresolved", "vocab"):
+        print(f"{k:12} {tally[k]}")
+    if symbols:
+        print("symbols written in the JSON itself (archify() leaves such a word as it is):",
+              ", ".join(f"{s}×{n}" for s, n in symbols.most_common()))
+
+
+if __name__ == "__main__":
+    main()

static/assets/pronunciation-rules.md

@@ -38,6 +38,8 @@
 | ה | נשיפה רכה, תמיד נשמעת | אַהְוֶה (קפה) |
 | א | עצירה קצרה בגרון | אַהְלַא (שלום) |
 | אַא, ִי, וּ | תנועה ארוכה: מחזיקים בערך כפול | כְּתִיר = ktiir |
+| ְ (שווא) | בלי תנועה: שני העיצורים צמודים. בתחילת משפט קשה להגות שווא, ולכן מותר שיישמע כמו e קצרה (צירה) | כְּתִיר = ktiir, ובתחילת משפט גם ketiir |
+| ֻ (קובוץ) | u קצרה אבל ברורה ומלאה, אף פעם לא נבלעת לשווא | מֻחַאמִי = muħaami, לא mħaami |
 | ּ (דגש) | עיצור כפול: מחזיקים אותו | חַמַּאם = ħam-maam |
 
 ---
@@ -217,6 +219,40 @@ checks:
   - {target: J, heard: [g, ɡ], severity: 1, feedback: "נהגתה g. בערבית פלסטינית ג' היא dʒ או ז'."}
 ```
 
+### 3.10 שני עיצורים צמודים · דיוק
+- **למה זה קשה:** בעברית מדוברת מוסיפים תנועה בין שני עיצורים שבאים ברצף (שווא נע), וכך גם בערבית: katiir במקום ktiir.
+- **מה עושים:** מצמידים את שני העיצורים, בלי תנועה ביניהם. בתחילת משפט קשה להגות שווא, ולכן שם מותר שיישמע כמו e קצרה (צירה).
+- **דוגמאות:** כְּתִיר = ktiir (לא katiir; בתחילת משפט גם ketiir), מְנִיח = mniiħ, בְּנְשוּף = bnʃuuf
+
+ה־scorer בודק תנועה שהמודל שומע בבירור בין שני עיצורים של אותה מילה. הוא לא בודק את הצרור שפותח את המשפט (6.3 #16), ולא צירוף עם w או j, שהמעבר אליהם נשמע כמו תנועה גם אצל דוברים ילידיים.
+
+```yaml
+id: cluster
+title: שני עיצורים צמודים
+insertion:
+  severity: 1
+  min_peak: 0.5      # a vowel the model is at least this sure of ...
+  min_frames: 2      # ... in at least this many frames (40 ms) between two consonants of one word
+  score_cap: 60      # the second consonant scores at most this
+  feedback: "נוספה תנועה בין שני העיצורים. הצמידו אותם, בלי תנועה ביניהם: ktiir ולא katiir. רק בתחילת משפט מותר e קצרה."
+```
+
+### 3.11 קובוץ ברור · דיוק
+- **למה זה קשה:** את השווא מותר להחליש, ודוברי עברית מחלישים גם תנועות קצרות אחרות. אבל u (קובוץ) היא תנועה מובחנת מאוד: מֻחַאמִי (עורך דין) היא muħaami, ולא mħaami.
+- **מה עושים:** הוגים את ה־u מלאה וברורה גם כשהיא קצרה, בלי להטעים אותה ובלי לבלוע אותה לשווא.
+- **דוגמאות:** מֻחַאמִי = muħaami, בֻּכְּרַה = bukra, מֻשְכִּלֶה = muʃkile
+
+זו התנועה הקצרה היחידה שה־scorer מסמן (ראו 6.3 #7), ורק אחרי עיצור באותה מילה, לא ו' החיבור.
+
+```yaml
+id: kubutz
+title: קובוץ ברור
+flag_vowels: [u]   # short u after a consonant is flagged, unlike the other short vowels (6.3 #7)
+checks:
+  - {target: u, heard: ["_"], severity: 1, feedback: "ה־u נבלעה. הגו אותה מלאה וברורה גם כשהיא קצרה: muħaami ולא mħaami."}
+  - {target: u, heard: [e, i, ə], severity: 1, feedback: "ה־u נשמעה כמו e או שווא. u היא תנועה מובחנת: עגלו את השפתיים, muħaami."}
+```
+
 ---
 
 <!-- audience: student -->
@@ -226,10 +262,9 @@ checks:
 
 | כלל | מה עושים | דוגמה |
 |---|---|---|
-| **הטעם לא בסוף המילה** | בעברית הטעם בדרך כלל בסוף המילה. בערבית מטעימים את ההברה הסגורה האחרונה שאינה בסוף המילה. | מֻשְ־כִּ־לֶה = **MUSH**-kile, מַדְ־רַ־סֶה = **MAD**-rase, בְּתִעְ־מַל = b**tiʕ**-mal |
+| **הטעם לא בסוף המילה** | בעברית הטעם בדרך כלל בסוף המילה, ודוברי עברית נוטים להטעים את ההברה האחרונה גם בערבית, בלי צורך. בערבית מטעימים את ההברה הסגורה או הארוכה האחרונה שאינה בסוף המילה. | מֻ־חַא־מִי (עורך דין) = mu-**ĦAA**-mi, לא muħaa-**MI** · מֻשְ־כִּ־לֶה = **MUSH**-kile, מַדְ־רַ־סֶה = **MAD**-rase, בְּתִעְ־מַל = b**tiʕ**-mal |
 | **ה סופית היא תנועה** | ה בסוף מילה היא לא אות שקטה. ברוב המילים נהגית e, ואחרי ח, ע, ר ועיצור מודגש נהגית a. בכפר שומעים לפעמים i. | אַהְוֶה, מֻשְכִּלֶה, אבל סַאעַה, מַחַטַּה |
 | **עיצור כפול** | מחזיקים את העיצור לפני שממשיכים. ההבדל משנה משמעות. | חַמַּאם (שירותים) ≠ ��ַמַאם (יונים) |
-| **שני עיצורים בהתחלה** | לא מוסיפים תנועה בין העיצורים. | כְּתִיר = ktiir (לא katiir), מְנִיח = mniiħ |
 | **אִל־ מתחברת** | לפני ת, ד, ס, צ, ש, ז, ר, נ, ט ו־ד' ה־ל נעלמת והעיצור מוכפל. | אִסְּסַאעַה (השעה), לא אִלְסַאעַה |
 
 ---
@@ -318,7 +353,7 @@ scoring:
 | 4 | אִל־ בלי התבוללות (il-saaʕa במקום is-saaʕa) | שגיאה קלה, וה־CTC לא מבחין בה באמינות | לא מסמנים. הכלל מופיע במדריך בלבד |
 | 5 | e מול a ב־ة סופית, וגם i בכפר | שונות לגיטימית | בהגה אחרון במילה שמקורה ב־ة: {a, e, i} שקולים |
 | 6 | o מול u בכינוי נסתר (בֵּיתוֹ/בֵּיתוּ) | הבדל בין ניבים | בהגה אחרון של כינוי: {o, u} שקולים |
-| 7 | שונות בתנועות קצרות (miʃ/muʃ, i/e, u/o) | שונות בין דוברים | תנועות קצרות לא מסומנות לעולם, רק אורך דרך כלל 3.8 |
+| 7 | שונות בתנועות קצרות (miʃ/muʃ, i/e, u/o) | שונות בין דוברים | תנועות קצרות לא מסומנות, רק אורך דרך כלל 3.8. חריג: u אחרי עיצור שנשמטה או נשמעה כ־e, i או שווא (3.11). u כ־o היא עדיין תנועה קרובה |
 | 8 | eː/aj ו־oː/aw (בֵּית/בַּיְת) | הגייה כפרית או ותיקה | {eː, aj} ו־{oː, aw} שקולים |
 | 9 | תנועה כהה ליד עיצור מודגש | זו בדיוק ההגייה הנכונה | אין כלל שמסמן איכות תנועה |
 | 10 | עיצור כפול (חַמַּאם) | ה־CTC מכווץ כפילות לטוקן אחד, ואין מדידת משך אמינה | לא נבדק. הכלל מופיע במדריך בלבד |
@@ -327,6 +362,7 @@ scoring:
 | 13 | g במקום `Q` | מבטא בדואי ודרומי | מתקבל רק אם `optional_realisations_enabled: true`. אחרת סומן כשגיאה כללית, חומרה 1 |
 | 14 | חזרה, היסוס או התחלה מחדש | הפענוח רחוק מכל וריאנט | `unrelated=true`, ציון עד 30, בלי טיפים |
 | 15 | הקלטה קצרה מדי או שקטה | אין חלון לכל הגה | `error: too_short` |
+| 16 | שווא בתחילת משפט נשמע כ־e (ketiir במקום ktiir) | קשה להגות צרור עיצורים בפתיחת המשפט | לא מסמנים: הצרור הראשון של המשפט פטור מכלל 3.10. באמצע משפט תנועה כזו מסומנת. בבדיקת "משפט אחר" היא נספרת כהבדל אחד |
 
 ---
 
@@ -345,6 +381,8 @@ scoring:
 | ה נבלעת | בינונית | |
 | אורך תנועה | נמוכה | חומרה 1 ו־`margin` גבוה |
 | טעם, כפילות, התבוללות | לא ניתן | מופיעים במדריך בלבד |
+| תנועה שנוספה בין עיצורים (katiir) | בינונית | נבדקת רק כשהמודל בטוח בתנועה (0.5) לפחות 40 ms. ליד ח, ע ו־ה המעבר עלול להישמע כתנועה גם אצל דובר ילידי |
+| קובוץ שנבלע או נהגה כ־e (mħaami) | בינונית | תנועות קצרות הן החלק החלש של המודל, ולכן חומרה 1 |
 
 ---
 
@@ -387,6 +425,7 @@ heard_labels:
   u: תנועה קצרה
   e: תנועה קצרה
   o: תנועה קצרה
+  ə: שווא
 ```
 
 ---

static/index.html

@@ -414,7 +414,19 @@ body:not(.manage) #manage,body.manage #wrap>header,body.manage #path,body.manage
 #manage.flags :is(#mClasses,#mContent,#mTutors,#mTabs,#mHead,#mLessons,#mRoster,#mStudent),#manage:not(.flags) #mFlags{display:none}
 .flag-review{gap:10px}.flag-review h2{margin:0}.flag-review .meta{color:var(--muted);font-size:13px}.flag-review fieldset{border:0;margin:0;padding:0;display:flex;flex-wrap:wrap;gap:7px}
 .flag-review fieldset label{display:flex;align-items:center;gap:5px;padding:6px 8px;border:1px solid var(--line);border-radius:9px}.flag-review select,.flag-review textarea{font:inherit;border:1px solid var(--line);border-radius:9px;padding:7px;background:var(--surface);color:var(--ink)}
-.flag-review textarea{width:100%;resize:vertical}.flag-patterns{width:100%;border-collapse:collapse;text-align:start}.flag-patterns :is(th,td){padding:6px;border-bottom:1px solid var(--line)}
+.flag-review textarea{width:100%;resize:vertical}
+.scoring-rules summary{cursor:pointer;font-size:17px}.scoring-rules details[open] summary{margin-bottom:8px}
+.scoring-rules .meta{color:var(--muted);font-size:13px}
+.rule-group h3{margin:14px 0 6px;font:700 14px/1.3 var(--f-body)}
+.rule-row{display:flex;align-items:flex-start;gap:10px;padding:8px 10px;border:1px solid var(--line);border-radius:10px;margin-bottom:6px;cursor:pointer}
+.rule-row input{margin-top:3px;width:17px;height:17px;flex:none}
+.rule-row.off{background:var(--bg);color:var(--muted)}
+.rule-text{display:flex;flex-wrap:wrap;gap:2px 8px;align-items:baseline}
+.rule-sec{font-size:12px;color:var(--muted)}
+.rule-desc{flex-basis:100%;font-size:13px;color:var(--muted)}
+.rule-note{flex-basis:100%;font-size:12px;color:var(--amber)}
+.rule-warn{padding:8px 10px;border-radius:10px;background:var(--amber-bg);color:var(--amber);font-size:13px}
+.rule-warn code{display:block;margin-top:4px;white-space:pre-wrap;word-break:break-all}.flag-patterns{width:100%;border-collapse:collapse;text-align:start}.flag-patterns :is(th,td){padding:6px;border-bottom:1px solid var(--line)}
 .activity{display:flex;flex-direction:column;gap:12px}.activity-head{display:flex;align-items:flex-start;justify-content:space-between;gap:12px;flex-wrap:wrap}.activity-head h2{margin:0}.activity-head p{margin:3px 0 0;color:var(--muted);font-size:13px}
 .activity-head select{font:inherit;padding:7px 10px;border:1px solid var(--line);border-radius:9px;background:var(--surface);color:var(--ink)}
 .activity-stats{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:8px}.activity-stat{padding:10px;border:1px solid var(--line);border-radius:10px;background:var(--bg)}.activity-stat b{display:block;font:400 28px/1 var(--f-display);font-variant-numeric:tabular-nums}.activity-stat small{color:var(--muted);font-size:12px}
@@ -613,7 +625,7 @@ dialog::backdrop{background:rgba(0,0,0,.45)}
 .stage-table .dec-flag{color:var(--sumac);font-weight:700}
 .stage-table .dec-issue{color:var(--amber);font-weight:700}
 .stage-table .dec-ok{color:var(--ok)}
-#stagesBox[data-hl="gop"] .st-gop,#stagesBox[data-hl="exemption"] .st-exemption,#stagesBox[data-hl="baseline"] .st-baseline,
+#stagesBox[data-hl="gop"] .st-gop,#stagesBox[data-hl="exemption"] .st-exemption,#stagesBox[data-hl="exemption"] .st-insertion,#stagesBox[data-hl="baseline"] .st-baseline,
 #stagesBox[data-hl="calibration"] .st-calibration,#stagesBox[data-hl="decision"] .st-decision,#stagesBox[data-hl="variant"] .st-variant,
 #stagesBox[data-hl="tips"] .st-tips{outline:2px solid var(--olive);outline-offset:-2px}
 #stagesBox[data-hl="word"] tr.stage-word td,#stagesBox[data-hl="sentence"] #stageSentence,#stagesBox[data-hl="unrelated"] #stageVariants{outline:2px solid var(--olive);outline-offset:-2px}
@@ -2289,9 +2301,10 @@ function drawStages(r){
     [["λ סלחנות",c.leniency],["p לביטחון מלא",c.confident_peak],["השמטה: p צפוי <",c.deleted_peak],["… וגם p מתחרה <",c.deleted_comp]],
     `100·e^(GOP·${c.leniency})·√min(1,p/${c.confident_peak})`,
     `${count(x=>stageOf(x,"gop").score<c.flag_below)} הגאים מתחת ל־${c.flag_below} · ${count(x=>x.deleted)} הושמטו`);
-  card("exemption",4,"פטורים (6.3)","מה שהמודל שומע כטעות אבל הוא דיבור רגיל.",
-    c.exemptions.map(e=>[EXEMPTION_NAMES[e]||e,e==="near_vowel"?"≥ "+c.near_vowel_floor:"100"]),null,
-    `${count(x=>stageOf(x,"exemption").applied)} פטורים הוחלו`);
+  card("exemption",4,"פטורים ותוספות","מה שהמודל שומע כטעות אבל הוא דיבור רגיל (6.3), ותנועה שנוספה בין עיצורים (3.10).",
+    [...c.exemptions.map(e=>[EXEMPTION_NAMES[e]||e,e==="near_vowel"?"≥ "+c.near_vowel_floor:"100"]),
+     ...(c.insertion?[["תנועה בין עיצורים: תקרה",c.insertion.score_cap],["… p תנועה ≥",c.insertion.min_peak],["… פריימים ≥",c.insertion.min_frames]]:[])],null,
+    `${count(x=>stageOf(x,"exemption").applied)} פטורים · ${count(x=>(stageOf(x,"insertion")||{}).applied)} תוספות תנועה`);
   card("baseline",5,"קו בסיס ילידי","ציון ההגה מחולק בציון שהמודל נותן לקול הילידי על אותו הגה.",
     [["הקלטות ילידיות",t.references.length],["ממוצע מינימלי לאמון",c.ref_min_mean]],"min(100, 100·score / ref)",
     `${count(x=>stageOf(x,"baseline").applied)} הגאים הותאמו`);
@@ -2340,7 +2353,7 @@ function drawStages(r){
   // every sound through the stages
   const tb=$("stageTable"); tb.innerHTML="";
   const head=[["#",""],["הגה","כתוב · סמל · מחלקה"],["חלון","פריימים",""],["P צפוי","","gop"],["מתחרה","P","gop"],["GOP","log יחס","gop"],
-    ["e^(GOP·λ)",`λ=${c.leniency}`,"gop"],["√ביטחון",`p/${c.confident_peak}`,"gop"],["ציון GOP","","gop"],["פטור","","exemption"],
+    ["e^(GOP·λ)",`λ=${c.leniency}`,"gop"],["√ביטחון",`p/${c.confident_peak}`,"gop"],["ציון GOP","","gop"],["פטור","","exemption"],["תנועה נוספת","3.10","insertion"],
     ["קו בסיס","ref","baseline"],["כיול","floor","calibration"],["סופי","",""],["מרווח","בפועל / נדרש","decision"],
     ["החלטה",`סימון <${c.flag_below} · רשימה <${c.issue_below}`,"decision"],["כלל","חומרה","tips"],["משקל","","sentence"]];
   const hr=E("tr"); for(const [a,b,st] of head){ const th=E("th",st?"st-"+st:"",a,b?E("small","",b):null); hr.append(th); } tb.append(E("thead","",hr));
@@ -2348,7 +2361,7 @@ function drawStages(r){
   t.words.forEach((w,wi)=>{
     body.append(E("tr","stage-word",(()=>{ const td=E("td","",`מילה ${wi+1}: ${w.tr} · ${num(w.score)}`,E("span","eq",`k·min + (1−k)·mean = ${c.word_min_weight}·${num(w.min)} + ${num(1-c.word_min_weight,2)}·${num(w.mean)} = ${num(w.score)}`)); td.colSpan=head.length; return td; })()));
     for(const x of toks.filter(x=>x.word===wi)){
-      const gop=stageOf(x,"gop"), ex=stageOf(x,"exemption"), bl=stageOf(x,"baseline"), cal=stageOf(x,"calibration");
+      const gop=stageOf(x,"gop"), ex=stageOf(x,"exemption"), ins=stageOf(x,"insertion")||{score:ex.score}, bl=stageOf(x,"baseline"), cal=stageOf(x,"calibration");
       const who=E("td","",ltr(x.ipa));
       if(x.sound!==x.ipa) who.append(E("small","",ltr(x.sound+(x.class?" {"+x.class.join(",")+"}":"")+(x.realised?" → "+x.realised:""))));
       const comp=E("td","st-gop",x.deleted?"הושמט":x.competitor_other?"צליל לא מוכר":x.competitor?ltr(x.competitor):"—",E("small","",pct(x.p_competitor)));
@@ -2357,6 +2370,7 @@ function drawStages(r){
       const m=x.margin, beyondTxt=m.beyond?"✓":"✗";
       let dec, decCls;
       if(x.flagged){ dec="מסומן"; decCls="dec-flag"; }
+      else if(ins.applied){ dec="תנועה מיותרת"; decCls="dec-flag"; }
       else if(x.issue){ dec="ברשימה"; decCls="dec-issue"; }
       else if(x.final<c.flag_below&&x.vowel){ dec="תנועה: לא מסומנת"; decCls="dec-issue"; }
       else if(x.final<c.flag_below&&!m.beyond){ dec="מרווח לא הושג"; decCls="dec-issue"; }
@@ -2370,6 +2384,7 @@ function drawStages(r){
         E("td","st-gop",ltr(num(x.gop,3))), E("td","st-gop",ltr(num(x.gop_factor,3))), E("td","st-gop",ltr(num(x.confidence_factor,3))),
         E("td","st-gop "+band(gop.score),num(gop.score)),
         step(ex,"exemption",ex.applied?(EXEMPTION_NAMES[ex.applied]||ex.applied):""),
+        step(ins,"insertion",ins.applied?"נוספה "+ins.applied:""),
         step(bl,"baseline",bl.ref!=null?"ref "+num(bl.ref):""),
         step(cal,"calibration",cal.floor!=null?"floor "+num(cal.floor):""),
         E("td",band(x.final),num(x.final)),
@@ -2864,6 +2879,7 @@ function sentence(p,under){   // a sentence as the student sees it, and a small
 let CLASS=null, shownClass=store.get("ihki.mstudentClass","*");   // "*" is every student; otherwise the class on show
 let mMode=store.get("ihki.mmode","");   // the panel's part on show: "classes" or "students" (the classes, before the first one)
 let FLAG_REVIEWS={pending:[],confirmed:[]}, CALIBRATIONS=[], ATTEMPT_PATTERNS=[], flagsError="", flagsLoaded=false, flagAudioUrls=[];
+let SCORING_RULES=null, scoringRulesError="";   // the rules of pronunciation-rules.md and whether each is on (see drawScoringRules)
 let ACTIVITY=null, activityError="";
 let activityHours=+store.get("ihki.activityHours","24"); if(![24,168].includes(activityHours)) activityHours=24;
 let shownStudent="", classScroll=0;   // the student whose screen is on show (an email; "" for the class's), and where the class's was left
@@ -2965,6 +2981,11 @@ async function loadFlags(){
       get("/api/calibrations","calibrations"),get("/api/attempt-patterns","patterns")]);
     FLAG_REVIEWS={pending,confirmed}; CALIBRATIONS=calibrations; ATTEMPT_PATTERNS=attemptPatterns; flagsLoaded=true;
   }catch(err){ flagsError=err.message; flagsLoaded=true; }
+  try{   // apart from the reports: a missing table here must not hide them
+    const res=await api("/api/scoring-rules"), data=await res.json().catch(()=>({}));
+    if(!res.ok) throw new Error(data.detail||res.status);
+    SCORING_RULES=data; scoringRulesError="";
+  }catch(err){ SCORING_RULES=null; scoringRulesError=err.message; }
   await activity;
 }
 function flagIssues(f){
@@ -2973,10 +2994,58 @@ function flagIssues(f){
     out.push({word,expected:p.ipa,heard:p.heard||"_",label:`${w.tr||w.ar}: ${p.ipa} ← ${p.heard||"חסר"}`});
   return out;
 }
+// The rules taken from pronunciation-rules.md, each with a switch. All are on by default; switching one off brings back
+// the behaviour from before the document, for every student, from the next recording on.
+const RULE_GROUPS={accept:"מה נחשב נכון (ניבים)",judge:"איך נשפטת טעות",feedback:"מה נאמר לתלמיד"};
+function drawScoringRules(box){
+  const card=mark("card scoring-rules",""), details=document.createElement("details"), summary=document.createElement("summary");
+  card.append(details); details.append(summary); box.append(card);
+  if(!SCORING_RULES){ summary.textContent="כללי ההגייה"; details.append(mark("msg","לא ניתן לטעון את הכללים: "+(scoringRulesError||""),"p")); return; }
+  const rules=SCORING_RULES.rules, on=rules.filter(r=>r.active).length;
+  summary.append(mark("","כללי ההגייה מהמסמך","b"),mark("meta",` · ${on} מתוך ${rules.length} פעילים`));
+  details.append(mark("meta","הכללים שנוספו לציון מתוך pronunciation-rules.md. כולם פעילים כברירת מחדל. כיבוי כלל מחזיר את ההתנהגות שלפני המסמך, לכל התלמידים, מההקלטה הבאה.","p"));
+  if(!SCORING_RULES.stored){
+    const warn=mark("rule-warn",""); warn.append(mark("","כדי לשנות כללים צריך ליצור את הטבלה scoring_rules. הריצו ב-SQL Editor של Supabase:","p"),mark("ltr",SCORING_RULES.create_sql,"code"));
+    details.append(warn);
+  }
+  const msg=mark("msg","");
+  const actions=mark("row",""), all=mark("btn","הפעלת כל הכללים","button");
+  all.disabled=!SCORING_RULES.stored||on===rules.length;
+  all.onclick=async()=>{ all.disabled=true; msg.textContent="שומר…";
+    try{ for(const r of rules.filter(r=>!r.active)){ const res=await api(`/api/scoring-rules/${r.id}`,{method:"PUT",headers:{"Content-Type":"application/json"},body:JSON.stringify({active:true})}); if(!res.ok) throw new Error((await res.json().catch(()=>({}))).detail||res.status); r.active=true; }
+      msg.textContent=""; box.innerHTML=""; drawFlags();
+    }catch(err){ msg.textContent="השמירה נכשלה: "+err.message; all.disabled=false; } };
+  actions.append(all,msg); details.append(actions);
+  for(const [group,label] of Object.entries(RULE_GROUPS)){
+    const list=rules.filter(r=>r.group===group); if(!list.length) continue;
+    const section=mark("rule-group",""); section.append(mark("",label,"h3"));
+    for(const r of list){
+      const row=document.createElement("label"), input=document.createElement("input"), text=mark("rule-text","");
+      row.className="rule-row"+(r.active?"":" off"); input.type="checkbox"; input.checked=r.active; input.disabled=!SCORING_RULES.stored;
+      text.append(mark("",r.title,"b"),mark("rule-sec",`סעיף ${r.section}`),mark("rule-desc",r.description,"span"));
+      if(!r.detectable) text.append(mark("rule-note","המודל הנוכחי לא מבחין בזה, כך שהכלל לא משנה דבר כרגע","span"));
+      if(r.updated_by) text.append(mark("rule-note",`${r.active?"הופעל":"כובה"} על ידי ${r.updated_by}`,"span"));
+      input.onchange=async()=>{
+        input.disabled=true; msg.textContent="שומר…";
+        try{
+          const res=await api(`/api/scoring-rules/${r.id}`,{method:"PUT",headers:{"Content-Type":"application/json"},body:JSON.stringify({active:input.checked})});
+          const data=await res.json().catch(()=>({})); if(!res.ok) throw new Error(data.detail||res.status);
+          r.active=input.checked; row.classList.toggle("off",!r.active); msg.textContent="";
+          summary.lastChild.textContent=` · ${rules.filter(x=>x.active).length} מתוך ${rules.length} פעילים`;
+          all.disabled=rules.every(x=>x.active);
+        }catch(err){ input.checked=!input.checked; msg.textContent="השמירה נכשלה: "+err.message; }
+        input.disabled=false;
+      };
+      row.append(input,text); section.append(row);
+    }
+    details.append(section);
+  }
+}
 function drawFlags(){
   const box=$("mFlags"); box.innerHTML=""; for(const url of flagAudioUrls) URL.revokeObjectURL(url); flagAudioUrls=[];
   drawActivity(box);
   if(!flagsLoaded){ box.append(mark("card","בחרו בניטור כדי לטעון את הנתונים.")); return; }
+  drawScoringRules(box);
   if(flagsError){ const card=mark("card",""); card.append(mark("","לא ניתן לטעון את הדיווחים","h2"),mark("",flagsError,"p")); box.append(card); return; }
   if(CALIBRATIONS.some(c=>c.status!=="rejected"&&!(c.evidence||{}).dismissed)){
     const list=mark("card",""); list.append(mark("","הצעות כיול","h2"));

tests/test_scoring.py

@@ -1561,6 +1561,7 @@ def test_a_tutor_flags_a_recording_scored_wrong(monkeypatch):
 
         def __init__(self):
             self.cls, self.flags, self.table, self.rank, self.calibration_rows = [], [], True, frozenset(), []
+            self.rule_rows = {}
 
         def user(self, token):
             return {"t": {"id": "u1", "email": "T@b.c"}, "s": {"id": "u2", "email": "s@b.c"}}.get(token)
@@ -1618,6 +1619,16 @@ def test_a_tutor_flags_a_recording_scored_wrong(monkeypatch):
             self.calibration_rows = [r for r in self.calibration_rows if r["id"] != calibration_id]
             return len(self.calibration_rows) < before
 
+        def scoring_rules(self):
+            if self.rule_rows is None:
+                raise AuthUnavailable("supabase answered 404: no table")
+            return list(self.rule_rows.values())
+
+        def set_scoring_rule(self, rule_id, active, by):
+            if self.rule_rows is None:
+                raise AuthUnavailable("supabase answered 404: no table")
+            self.rule_rows[rule_id] = {"id": rule_id, "active": active, "updated_by": by}
+
         def all_attempt_issues(self):
             return [{"user_id": f"u{i}", "phrase": TOILET["he"], "score": 60,
                      "issues": [{"expected": "ħ", "heard": "χ", "score": 20}],
@@ -1677,6 +1688,21 @@ def test_a_tutor_flags_a_recording_scored_wrong(monkeypatch):
                            "evidence": {"dismissed": True, "source": "confirmed_flags"}})
         assert dismissed.status_code == 200 and dismissed.json()["calibration"]["status"] == "draft"
         assert dismissed.json()["calibration"]["evidence"] == {"dismissed": True, "source": "confirmed_flags"}
+        # the rules of pronunciation-rules.md: all on, a teacher switches one off, and the scorer follows at once
+        listed = c.get("/api/scoring-rules", headers=hs).json()
+        assert listed["stored"] and all(r["active"] for r in listed["rules"]) and len(listed["rules"]) >= 20
+        assert all(isinstance(r["detectable"], bool) and r["title"] and r["description"] for r in listed["rules"])
+        assert c.put("/api/scoring-rules/dialect_Q", headers=hs, json={"active": False}).json()["disabled"] == ["dialect_Q"]
+        assert c.app.state.scorer.disabled == {"dialect_Q"} and a.rule_rows["dialect_Q"]["updated_by"] == "s@b.c"
+        assert not next(r for r in c.get("/api/scoring-rules", headers=hs).json()["rules"] if r["id"] == "dialect_Q")["active"]
+        assert c.put("/api/scoring-rules/nope", headers=hs, json={"active": False}).status_code == 400
+        assert c.put("/api/scoring-rules/margins", headers=hs, json={"active": "no"}).status_code == 400
+        assert c.put("/api/scoring-rules/margins", headers={"Authorization": "Bearer t"}, json={"active": False}).status_code == 403
+        assert c.put("/api/scoring-rules/dialect_Q", headers=hs, json={"active": True}).json()["disabled"] == []
+        a.rule_rows = None   # no table yet: the list still shows, all on, with the SQL to create it
+        missing = c.get("/api/scoring-rules", headers=hs).json()
+        assert not missing["stored"] and "create table public.scoring_rules" in missing["create_sql"]
+        assert c.put("/api/scoring-rules/margins", headers=hs, json={"active": False}).status_code == 503
         a.teachers = frozenset()
         a.table = False   # before the table is created: the command to create it
         r = send(c, "t")
@@ -1708,6 +1734,88 @@ def test_a_tutor_flags_a_recording_scored_wrong(monkeypatch):
         assert r.status_code == 503 and "create table public.tutors" in r.json()["detail"]
 
 
+def test_switched_off_rules_bring_back_the_old_behaviour():
+    kaddeesh = emissions(["k", "a", "d", "eː", "ʃ", "i", "s", "aː", "ʕ", "a"])
+    s = scorer_for(kaddeesh)
+    assert not s.score(None, TIME)["tips"]                                    # rural ق accepted
+    s.set_disabled({"dialect_Q", "not-a-rule"})
+    assert s.disabled == {"dialect_Q"}
+    assert [t["key"] for t in s.score(None, TIME)["tips"]] == ["ʔ>k"]          # as before the document
+    # the emphatic margin: off, plain t winning by less than twice is a mistake again
+    phrase = {"variants": [("طين", "tˤ i n")]}
+    s = margin_scorer(1.8)
+    assert not s.score(None, phrase)["tips"]
+    s.set_disabled({"margins"})
+    assert [t["key"] for t in s.score(None, phrase)["tips"]] == ["tˤ>t"]
+    # a section-3 rule off: the general tip and severity instead of the document's
+    s = custom_scorer(["p", "f", "dʒ"], ["p", "i", "n", "dʒ", "aː", "n"])
+    fin = {"variants": [("فنجان", "f i n dʒ aː n")]}
+    assert s.score(None, fin)["tips"][0]["text"].startswith("נהגתה p")
+    s.set_disabled({"rule_f"})
+    tip = s.score(None, fin)["tips"][0]
+    assert tip["key"] == "f>p" and not tip["text"].startswith("נהגתה p") and tip["severity"] == 2
+    # the final vowel of ة: off, i for e is marked down like any other vowel
+    s = scorer_for(emissions(["ʔ", "a", "h", "w", "i"]))
+    assert s.score(None, COFFEE)["words"][0]["phonemes"][-1]["score"] >= 95
+    s.set_disabled({"final_vowel", "near_vowel"})
+    assert s.score(None, COFFEE)["words"][0]["phonemes"][-1]["score"] < 50
+
+
+THANKS = {"variants": [("شكرا كتير", "ʃ u k r a n | k t iː r")]}
+CLUSTER_SYMS = ["r", "t", "iː", "u", "ʃ"]
+
+
+def test_vowel_between_two_consonants_is_a_mistake_mid_sentence():
+    clean = custom_scorer(CLUSTER_SYMS, ["ʃ", "u", "k", "r", "a", "n", "k", "t", "iː", "r"]).score(None, THANKS)
+    assert not clean["tips"] and clean["score"] >= 95
+    s = custom_scorer(CLUSTER_SYMS, ["ʃ", "u", "k", "r", "a", "n", "k", "a", "t", "iː", "r"])   # katiir
+    r = s.score(None, THANKS)
+    t = next(p for p in r["words"][1]["phonemes"] if p["ipa"] == "t")
+    assert t["inserted"] == "a" and t["score"] == 60 and [x["key"] for x in r["tips"]] == ["cluster"]
+    assert r["tips"][0]["severity"] == 1 and "ktiir" in r["tips"][0]["text"] and r["score"] < clean["score"]
+    letter = next(l for l in r["words"][1]["letters"] if "ת" in l["t"])
+    assert letter["why"].startswith("נוספה") and "ktiir" in letter["tip"]
+    s.set_disabled({"rule_cluster"})                       # switched off: not checked, as before
+    assert not s.score(None, THANKS)["tips"]
+
+
+def test_vowel_in_the_cluster_that_opens_the_sentence_is_fine():
+    # ketiir at the start of a sentence (6.3 #16), and the way into a glide (shuway)
+    r = custom_scorer(["t", "iː", "r"], ["k", "e", "t", "iː", "r"]).score(None, {"variants": [("كتير", "k t iː r")]})
+    assert not r["tips"] and r["score"] >= 95
+    phrase = {"variants": [("شو شوي", "ʃ u | ʃ w a j j")]}
+    r = custom_scorer(["ʃ", "u", "j"], ["ʃ", "u", "ʃ", "u", "w", "a", "j"]).score(None, phrase)
+    assert not any(t["key"] == "cluster" for t in r["tips"])
+
+
+LAWYER = {"variants": [("محامي", "m u ħ aː m i")]}
+
+
+@pytest.mark.parametrize("said,flagged", [
+    (["m", "u", "ħ", "aː", "m", "i"], False),
+    (["m", "ħ", "aː", "m", "i"], True),            # mħaami: the u swallowed
+    (["m", "e", "ħ", "aː", "m", "i"], True),       # said as e
+    (["m", "o", "ħ", "aː", "m", "i"], False),      # o is a near vowel
+])
+def test_kubutz_is_a_distinct_vowel(said, flagged):
+    r = custom_scorer(["u", "o"], said).score(None, LAWYER)
+    u = r["words"][0]["phonemes"][1]
+    assert u["ipa"] == "u" and u["flagged"] == flagged, u
+    if flagged:
+        assert r["tips"][0]["text"].startswith("ה־u") and r["tips"][0]["severity"] == 1
+
+
+def test_only_short_u_after_a_consonant_is_flagged():
+    s = custom_scorer(["u", "o"], ["m", "ħ", "aː", "m", "i"])
+    s.set_disabled({"rule_kubutz"})                       # switched off: like any other short vowel
+    assert not s.score(None, LAWYER)["words"][0]["phonemes"][1]["flagged"]
+    # the و of "and" (u m a) and a long uː (ʃ uː f) are not the kubutz rule's
+    r = custom_scorer(["u"], ["m", "a"]).score(None, {"variants": [("وما", "u m a")]})
+    assert not r["words"][0]["phonemes"][0]["flagged"]
+    r = custom_scorer(["u", "uː", "f", "ʃ"], ["ʃ", "e", "f"]).score(None, {"variants": [("شوف", "ʃ uː f")]})
+    assert not r["words"][0]["phonemes"][1]["flagged"] and not r["tips"]
+
+
 def test_teacher_trace_follows_every_stage():
     # ħ said as χ, then forgiven by a teacher floor: each stage of the trace shows where the score came from
     logp = emissions(["w", "eː", "n", "i", "l", "χ", "a", "m", "aː", "m"])
@@ -1717,7 +1825,7 @@ def test_teacher_trace_follows_every_stage():
     t = scorer.score_logp(logp, TOILET, diagnostics=True)["trace"]
     assert t["config"]["flag_below"] == 50 and t["config"]["leniency"] == 0.5 and t["variants"][0]["chosen"]
     h = next(x for x in t["tokens"] if x["ipa"] == "ħ")
-    assert [s["stage"] for s in h["stages"]] == ["gop", "exemption", "baseline", "calibration"]
-    assert h["stages"][0]["score"] < 50 and h["stages"][3]["applied"] and h["final"] == 60
+    assert [s["stage"] for s in h["stages"]] == ["gop", "exemption", "insertion", "baseline", "calibration"]
+    assert h["stages"][0]["score"] < 50 and h["stages"][4]["applied"] and h["final"] == 60
     assert h["competitor"] == "χ" and h["rule"]["severity"] == 3 and not h["flagged"]
     assert t["sentence"]["final"] == round(0.5 * t["sentence"]["phone_mean"] + 0.5 * t["sentence"]["word_mean"])