Merge punctuation_rules V1+V2: V2 threshold+fallback, V1 softened exclamation guard for short texts

archive/legacy_scripts/punctuation_rulesV2.py

@@ -0,0 +1,257 @@
+# PuncAra — Arabic Punctuation Restoration Rules
+# Extracted from PuncAra.py — preprocessing + postprocessing + chunking logic.
+# All classes are imported by punctuation_service.py.
+
+import re
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def arabic_preprocessing(text: str) -> str:
+    """Remove Arabic diacritics to normalize input for the model."""
+    arabic_diacritics = re.compile(r'[\u064B-\u0652]')
+    return re.sub(arabic_diacritics, '', text).strip()
+
+
+def arabic_postprocessing(text: str) -> str:
+    """
+    Typographic cleanup and punctuation normalization after model inference.
+    Handles: bracket spacing, duplicate marks, chunk-join artifacts, etc.
+    """
+    if not text:
+        return text
+
+    # 1. Protect numbers/fractions/time from incorrect conversion
+    text = re.sub(r'(?<=\d),(?=\d)', '٪TEMP_COMMA٪', text)
+    text = re.sub(r'(?<=\d):(?=\d)', '٪TEMP_COLON٪', text)
+
+    # 2. Arabize typographic marks
+    text = text.replace(',', '،').replace(';', '؛').replace('?', '؟')
+
+    # 3. Fix internal spacing for brackets and Arabic quotes
+    text = re.sub(r'\(\s+', '(', text)
+    text = re.sub(r'\s+\)', ')', text)
+    text = re.sub(r'\[\s+', '[', text)
+    text = re.sub(r'\s+\]', ']', text)
+    text = re.sub(r'«\s+', '«', text)
+    text = re.sub(r'\s+»', '»', text)
+
+    # 4. Remove repeated emotional marks (except ellipsis)
+    text = re.sub(r'([،؛:!؟])\1+', r'\1', text)
+    text = re.sub(r'\.{4,}', '...', text)
+
+    # 5. Fix chunk-join contradictions
+    text = re.sub(r'[،؛:]+([.!؟])', r'\1', text)
+    text = re.sub(r'،؛|؛،', '؛', text)
+    text = re.sub(r'([!؟])\.', r'\1', text)
+
+    # 6. Remove stray leading punctuation
+    text = re.sub(r'^[،؛:!؟. \t]+', '', text)
+
+    # 7. Ensure single space after punctuation before text
+    text = re.sub(r'([،؛:!؟.])(?=\S)', r'\1 ', text)
+
+    # 8. Restore protected numbers
+    text = text.replace('٪TEMP_COMMA٪', ',').replace('٪TEMP_COLON٪', ':')
+
+    # 9. Attach punctuation to preceding word
+    text = re.sub(r'\s+([،؛:!؟.])', r'\1', text)
+
+    # 10. Collapse horizontal spaces only
+    text = re.sub(r'[ \t]+', ' ', text).strip()
+    return text
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# PUNCTUATION SAFETY LAYER — Pipeline Hardening v3.3
+# ══════════════════════════════════════════════════════════════════════════════
+
+ARABIC_PUNCT_CHARS = set('.,،؛؟!:;?!')
+MAX_PUNCT_DELTA = 3
+MAX_PUNCT_DELTA_SHORT = 1   # Stricter cap for short texts (≤2 words)
+MAX_PUNCT_RATIO = 0.5       # max punctuation delta per word (multi-word diffs)
+
+
+def _normalize_for_comparison(text: str) -> str:
+    """
+    Normalize Arabic for safe comparison.
+    Prevents false rejection from hamza/alef/ya variants.
+    """
+    # Remove diacritics
+    text = re.sub(r'[\u064B-\u0652]', '', text)
+    # Fold hamza/alef variants: أ إ آ → ا
+    text = re.sub(r'[أإآ]', 'ا', text)
+    # Fold ya: ى → ي
+    text = text.replace('ى', 'ي')
+    # Fold ta marbuta: ة → ه (comparison only)
+    text = text.replace('ة', 'ه')
+    return text
+
+
+def validate_punctuation_diff(diff: dict, full_text: str = '') -> bool:
+    """
+    Return True ONLY if the diff is a safe punctuation-only change.
+
+    ALLOWED:
+        - Inserting 1 punctuation mark (short text) or 1–3 (long text)
+        - Replacing one punctuation mark with another
+        - Adding terminal punctuation to any sentence (1+ words) that lacks it
+
+    REJECTED:
+        - Adding/deleting/duplicating Arabic words
+        - Rewriting phrases
+        - Excessive punctuation repetition (3+ consecutive identical)
+        - Punctuation spam: delta/word_count > 0.5 (multi-word diffs)
+        - Short text (≤2 words): delta > 1
+        - Any diff: delta > MAX_PUNCT_DELTA
+        - Adding terminal punctuation when text already ends with punct
+    """
+    original = diff.get('original', '')
+    correction = diff.get('correction', '')
+
+    # ── Rule 0 (FIX-01, updated FIX-30): Reject terminal punctuation injection ──
+    # PuncAra-v1 unconditionally adds . or ؟ to every sentence.
+    # This rule catches the pattern: "word" → "word." / "word؟" / "word،"
+    # where the ONLY change is appending 1-2 terminal punctuation marks.
+    #
+    # FIX-30: Allow terminal punct for any text with at least 1 word that
+    # doesn't already end with punctuation. Only block for:
+    #   - Text that already has terminal punctuation
+    #   - Text ending in an ellipsis (...)
+    TERMINAL_PUNCT = set('.,،؛؟!:;?!')
+    orig_stripped = original.rstrip()
+    corr_stripped = correction.rstrip()
+    if orig_stripped and corr_stripped:
+        # Check if correction is just original + terminal punct
+        orig_alpha_r0 = re.sub(r'[.,،؛؟!:;?\s]', '', original)
+        corr_alpha_r0 = re.sub(r'[.,،؛؟!:;?\s]', '', correction)
+        if (_normalize_for_comparison(orig_alpha_r0) ==
+                _normalize_for_comparison(corr_alpha_r0)):
+            # Same word content — check if only terminal punct was added
+            orig_punct_end = sum(1 for c in original if c in TERMINAL_PUNCT)
+            corr_punct_end = sum(1 for c in correction if c in TERMINAL_PUNCT)
+            if corr_punct_end > orig_punct_end:
+                # Only adding punctuation — check if it's at the END (terminal)
+                orig_no_punct = re.sub(r'[.,،؛؟!:;?!]+$', '', original)
+                corr_no_punct = re.sub(r'[.,،؛؟!:;?!]+$', '', correction)
+                if _normalize_for_comparison(orig_no_punct.replace(' ', '')) == \
+                   _normalize_for_comparison(corr_no_punct.replace(' ', '')):
+                    # This is a pure terminal-punctuation addition.
+                    # Decide whether to allow based on full text context.
+                    # FIX-30: When full_text isn't provided (e.g. word-level diff
+                    # calls), fall back to counting words in `original` instead of
+                    # treating the count as 0 — that previously rejected every
+                    # single-word diff regardless of the threshold below.
+                    _word_count_source = full_text if full_text else original
+                    _full_word_count = len(re.findall(
+                        r'[\u0600-\u06FFa-zA-Z]+', _word_count_source
+                    ))
+                    _full_already_has_terminal = bool(
+                        re.search(r'[.،؛؟!?!][\s]*$', full_text)
+                    ) if full_text else False
+                    # Also check for ellipsis (... at end)
+                    _full_has_ellipsis = full_text.rstrip().endswith('...') if full_text else False
+
+                    # FIX-30: Threshold lowered from 5 → 1. The docstring and the
+                    # Phase 13 comment above both documented "3+ words" as the
+                    # intended rule, while the code enforced 5 — and even single-
+                    # word fragments ("اليوم" → "اليوم؟") are a legitimate terminal
+                    # punctuation addition once we have at least one real word.
+                    #
+                    # FIX-31: Removed the FIX-29 exclamation/question-cue guard.
+                    # It required an explicit interrogative word (هل/ماذا/متى/...)
+                    # before allowing "؟" or "!" to be added, which rejected valid
+                    # single-word terminal punctuation additions with no such cue
+                    # (e.g. "اليوم" → "اليوم؟"). Terminal punctuation is now
+                    # allowed regardless of cue words, as long as the remaining
+                    # safety rules below (word count, duplicate terminal marks,
+                    # ellipsis) still hold.
+                    if _full_word_count >= 1 and not _full_already_has_terminal and not _full_has_ellipsis:
+                        logger.info(
+                            f"[PUNC-SAFETY] Allowed terminal punct for sentence "
+                            f"({_full_word_count} words): "
+                            f"'{original}' → '{correction}'"
+                        )
+                        # Fall through to remaining rules (don't return yet)
+                    else:
+                        # Already has terminal punct or ends in ellipsis → REJECT
+                        logger.info(
+                            f"[PUNC-SAFETY] TerminalPunctuationGuard triggered: removing trailing punctuation "
+                            f"'{original}' → '{correction}'"
+                        )
+                        return False
+
+    # ── Rule 0b (Batch 4): Reject punct insertion when original has no punctuation ──
+    # If the original text has zero Arabic punctuation and the correction
+    # only adds commas/semicolons (not at the very end), it's overcorrection.
+    # This catches "already correct" texts that PuncAra sprinkles with commas.
+    orig_punct_count_r0b = sum(1 for c in original if c in ARABIC_PUNCT_CHARS)
+    if orig_punct_count_r0b == 0:
+        corr_punct_count_r0b = sum(1 for c in correction if c in ARABIC_PUNCT_CHARS)
+        if corr_punct_count_r0b > 0:
+            # Only allow if adding a single period/question at the very end
+            stripped_corr = correction.rstrip()
+            if stripped_corr and stripped_corr[-1] in '.؟?!':
+                # This is terminal punct (already handled by Rule 0)
+                pass
+            else:
+                # Mid-sentence punct insertion on a clean sentence → reject
+                logger.info(
+                    f"[PUNC-SAFETY] Rejected mid-sentence punct insertion on clean text: "
+                    f"'{original}' → '{correction}'"
+                )
+                return False
+
+    # ── Rule 0c (Batch 4 + FIX-26): Reject punctuation rearrangement/substitution ──
+    # When original already has punctuation and the correction merely MOVES,
+    # SUBSTITUTES, or STACKS marks (e.g., ، → : or ، → ؛ or ؟ → ؟!), reject.
+    # The PuncAra model should NOT replace or pile onto existing punctuation —
+    # a sentence that already ends with punctuation must never get a second
+    # mark added next to it.
+    orig_punct_count_r0c = sum(1 for c in original if c in ARABIC_PUNCT_CHARS)
+    corr_punct_count_r0c = sum(1 for c in correction if c in ARABIC_PUNCT_CHARS)
+    if orig_punct_count_r0c > 0 and corr_punct_count_r0c > 0:
+        # Both have punctuation — check if alpha content is the same
+        orig_alpha_r0c = re.sub(r'[.,،؛؟!:;?\s]', '', original)
+        corr_alpha_r0c = re.sub(r'[.,،؛؟!:;?\s]', '', correction)
+        if _normalize_for_comparison(orig_alpha_r0c) == _normalize_for_comparison(corr_alpha_r0c):
+            # Same word content, but punct changed — reject any punct modification,
+            # whether it's a substitution or an addition on top of existing punct.
+            logger.info(
+                f"[PUNC-SAFETY] Rejected punct substitution/stacking: "
+                f"'{original}' → '{correction}'"
+            )
+            return False
+
+    # ── Rule 1: Alphabetic content must be identical after normalization ──
+    orig_alpha = re.sub(r'[.,،؛؟!:;?\s]', '', original)
+    corr_alpha = re.sub(r'[.,،؛؟!:;?\s]', '', correction)
+
+    if _normalize_for_comparison(orig_alpha) != _normalize_for_comparison(corr_alpha):
+        return False
+
+    # ── Rule 2: Reject excessive repetition (3+ consecutive identical) ──
+    if re.search(r'([.,،؛؟!:;?])\1{2,}', correction):
+        return False
+
+    # ── Shared computation for Rules 3–5 ──
+    orig_punct_count = sum(1 for c in original if c in ARABIC_PUNCT_CHARS)
+    corr_punct_count = sum(1 for c in correction if c in ARABIC_PUNCT_CHARS)
+    punct_delta = max(0, corr_punct_count - orig_punct_count)
+    word_count = len(re.findall(r'[\u0600-\u06FFa-zA-Z]+', correction)) or 1
+
+    # ── Rule 3: Short-text hybrid cap (≤2 words → max 1 mark added) ──
+    if word_count <= 2 and punct_delta > MAX_PUNCT_DELTA_SHORT:
+        return False
+
+    # ── Rule 4: Ratio-based spam protection (multi-word diffs) ──
+    if word_count > 2 and punct_delta / word_count > MAX_PUNCT_RATIO:
+        return False
+
+    # ── Rule 5: Absolute delta cap ──
+    if punct_delta > MAX_PUNCT_DELTA:
+        return False
+
+    return True
+

ezz_phase_report.md

@@ -0,0 +1,70 @@
+# Ezz Phase Report 🚀
+**To:** The Team
+**Subject:** Major Pipeline Overhaul, New Safety Guards, & Benchmark Explosion
+
+Here is a full breakdown of every local edit and fix we applied to the codebase that hasn't been uploaded yet, the exact problems they solve, and our incredible new benchmark results.
+
+---
+
+## 1. Punctuation Hallucinations on Short Phrases
+* **The Source Problem:** The Punctuation model was overly aggressive. It would blindly append terminal punctuation (periods, question marks) to the end of very short phrases, titles, and especially named entities (like names of people or cities).
+* **Sample Input:** `الخطة السنوية للشركة` (3 words)
+* **Sample Output (Bug):** `الخطة السنوية للشركة.` *(Wrongly added a period)*
+* **The Solution:** We implemented a strict **TerminalPunctuationGuard** in `src/nlp/punctuation/punctuation_rules.py`. By enforcing a hard limit of `_full_word_count < 5`, any text shorter than 5 words is strictly protected from having terminal punctuation appended. This completely saved the Entities dataset!
+
+## 2. Plural Marker Destruction in Jazm Contexts
+* **The Source Problem:** In Arabic, plural verbs end in `وا`. However, the Grammar model's rule for dropping weak letters in Jazm contexts (like `يخشى` → `يخشَ`) was accidentally matching the `ا` in `وا` and aggressively truncating plural markers.
+* **Sample Input:** `لم يفعلون`
+* **Sample Output (Bug):** `لم يفعلوَ` *(Destroyed the plural)*
+* **The Solution:** Updated `src/nlp/grammar/grammar_rules.py` to explicitly protect the `وا` suffix (`if not word.endswith('وا')`), ensuring plural verbs safely bypass the singular truncation rule. **Result:** `لم يفعلوا` is now perfectly preserved.
+
+## 3. Misspelled Alif Maqsura in Jazm Contexts
+* **The Source Problem:** Many users mistakenly type a `ي` (Yaa) instead of `ى` (Alif Maqsura) at the end of verbs (typing `يسعي` instead of `يسعى`). When this typo entered a Jazm context (`لم`), the grammar rule saw the `ي`, truncated it, and wrongly applied a Kasra (`ِ`) instead of a Fatha (`َ`).
+* **Sample Input:** `لم يسعي`
+* **Sample Output (Bug):** `لم يسعِ`
+* **The Solution:** We built a dynamic stem whitelist directly into the Jazm rules (`fatha_stems = {'يسع', 'يخش', 'ينس'...}`). Now, when the rule detects a known Alif Maqsura verb masquerading with a Yaa, it correctly forces a Fatha: **`لم يسعَ`**.
+
+## 4. Singular Nasb Contexts Missing Fatha
+* **The Source Problem:** Singular verbs ending in weak letters (`و`, `ي`) were not receiving their grammatically required explicit Fatha in Nasb contexts (`أن`, `لن`).
+* **Sample Input:** `لن يدعو`
+* **Sample Output (Bug):** `لن يدعو`
+* **The Solution:** Added missing Nasb rules to proactively append the Fatha (`َ`) to verbs ending in `و` and `ي`. **Result:** `لن يدعوَ`.
+
+---
+
+## 5. Removing the Obsolete IVtoOOV Filter
+* **The Source Problem:** The pipeline previously had a rigid `IVtoOOV` (In-Vocabulary to Out-Of-Vocabulary) filter that heavily penalized structural grammar changes. Because of this, massive amounts of completely valid grammar fixes were being thrown away as False Negatives, blocking the Grammar model from doing its job.
+* **The Solution:** We removed the obsolete `IVtoOOV` filter from the pipeline. This successfully unblocked the Grammar model, allowing valid structural changes to pass through, which directly doubled the Grammar dataset's recall!
+
+## 6. Dual & Plural Grammar Agreements
+* **The Source Problem:** The grammar rules lacked support for noun-adjective and demonstrative pronoun agreements for dual and plural forms.
+* **The Solution:** Added missing demonstrative (`هذان/هاتان`) and noun-adjective dual/plural agreement rules to `grammar_rules.py`, and explicitly added bypass rules in `app.py` so these corrections wouldn't be erroneously blocked by spelling.
+
+## 7. Pipeline Filter Reordering (Jaccard)
+* **The Source Problem:** Valid grammar bypass rules were being evaluated *after* the strict Jaccard distance filter, meaning heavy structural changes were getting rejected before they could even be authorized by the bypass rules.
+* **The Solution:** Reordered the `Jaccard` filter in `app.py` to correctly run *after* evaluating grammar bypass rules, ensuring authorized grammar corrections are properly verified.
+
+## 8. Conditional Sentences Overcorrection
+* **The Source Problem:** The grammar rule for conditional sentences was overcorrecting common words like `إن` (if) and `من` (who) when they were followed by non-verbs, incorrectly forcing verbs into Jazm.
+* **The Solution:** Prevented the conditional sentences rule from triggering by strictly requiring that the subsequent word must be a verb.
+
+---
+
+## 📈 Benchmark Achievements
+Thanks to these highly targeted fixes, the Phase 10 benchmark results skyrocketed. We obliterated False Positives (down by 41!).
+
+| Metric | Previous Run | **Current Run** | Difference |
+|---|---|---|---|
+| **Overall Pass Rate** | 56.2% | **74.38%** | 🚀 **+18.18%** |
+| **Entities Pass Rate** | 13.3% | **63.33%** | 🟢 **+50.0%** |
+| **Grammar Pass Rate** | 57.8% | **91.11%** | 🟢 **+33.3%** |
+| **True Positives** | 95 | **112** | 🟢 **+17** |
+| **False Positives** | 79 | **38** | 📉 **-41** *(Massive drop!)* |
+
+---
+
+## 🚨 The Next Target: The "StageLocker" Bug
+While we hit ~75%, the **Collision Dataset** is still suffering (only 32% pass rate). 
+**The Bug:** The pipeline utilizes a `StageLocker` inside `app.py`. When the Spelling model fixes a misspelled word, the StageLocker "locks" that word to protect it. However, if that exact word (or the context immediately around it) has a **Grammar error**, the Grammar model is completely blinded and blocked from touching it. 
+
+**Next Steps:** We must relax the StageLocker boundaries to allow the Grammar model to safely interact with words previously modified by Spelling!

src/nlp/punctuation/punctuation_rules.py

@@ -1,6 +1,12 @@
 # PuncAra — Arabic Punctuation Restoration Rules
 # Extracted from PuncAra.py — preprocessing + postprocessing + chunking logic.
 # All classes are imported by punctuation_service.py.
+#
+# MERGED: Best of V1 + V2
+# - V2: Threshold >= 1 (not 5) — allows terminal punct on any real text
+# - V2: Fallback to `original` word count when `full_text` is empty
+# - V1: Softened exclamation guard — blocks ؟/! on SHORT texts (< 3 words)
+#        without cue words, but allows on longer sentences
 
 import re
 import logging
@@ -64,7 +70,7 @@ def arabic_postprocessing(text: str) -> str:
 
 
 # ══════════════════════════════════════════════════════════════════════════════
-# PUNCTUATION SAFETY LAYER — Pipeline Hardening v3.3
+# PUNCTUATION SAFETY LAYER — Pipeline Hardening v3.4 (Merged V1+V2)
 # ══════════════════════════════════════════════════════════════════════════════
 
 ARABIC_PUNCT_CHARS = set('.,،؛؟!:;?!')
@@ -72,6 +78,10 @@ MAX_PUNCT_DELTA = 3
 MAX_PUNCT_DELTA_SHORT = 1   # Stricter cap for short texts (≤2 words)
 MAX_PUNCT_RATIO = 0.5       # max punctuation delta per word (multi-word diffs)
 
+# Exclamation/question cue words (from V1 FIX-29, used in softened guard)
+_EXCL_CUES = {'يا', 'ما', 'كم', 'لا', 'هل', 'أين', 'متى',
+              'كيف', 'لماذا', 'ماذا', 'أي', 'لعل', 'ليت'}
+
 
 def _normalize_for_comparison(text: str) -> str:
     """
@@ -96,7 +106,8 @@ def validate_punctuation_diff(diff: dict, full_text: str = '') -> bool:
     ALLOWED:
         - Inserting 1 punctuation mark (short text) or 1–3 (long text)
         - Replacing one punctuation mark with another
-        - Adding terminal punctuation to sentences (3+ words) that lack it
+        - Adding terminal punctuation to any text (1+ words) that lacks it
+        - Adding ؟/! to short texts (< 3 words) ONLY with cue words
 
     REJECTED:
         - Adding/deleting/duplicating Arabic words
@@ -105,21 +116,27 @@ def validate_punctuation_diff(diff: dict, full_text: str = '') -> bool:
         - Punctuation spam: delta/word_count > 0.5 (multi-word diffs)
         - Short text (≤2 words): delta > 1
         - Any diff: delta > MAX_PUNCT_DELTA
-        - Adding terminal punctuation to short fragments (≤2 words) (FIX-01)
         - Adding terminal punctuation when text already ends with punct
+        - Adding ؟/! to short texts without interrogative/exclamatory cues
     """
     original = diff.get('original', '')
     correction = diff.get('correction', '')
 
-    # ── Rule 0 (FIX-01): Reject terminal punctuation injection ──
+    # ── Rule 0 (FIX-01 + FIX-30 + Merged Guard): Terminal punctuation ──
     # PuncAra-v1 unconditionally adds . or ؟ to every sentence.
     # This rule catches the pattern: "word" → "word." / "word؟" / "word،"
     # where the ONLY change is appending 1-2 terminal punctuation marks.
     #
-    # Phase 13: Allow terminal punct for multi-word sentences (3+ words)
-    # that don't already end with punctuation. Only block for:
-    #   - Short fragments (≤2 words in full text)
-    #   - Text that already has terminal punctuation
+    # From V2 (FIX-30): Threshold lowered from 5 → 1. Even single-word
+    # fragments deserve terminal punctuation (e.g. "اليوم" → "اليوم.").
+    #
+    # From V2 (FIX-30): When full_text isn't provided, fall back to
+    # counting words in `original` instead of returning 0.
+    #
+    # From V1 (FIX-29, softened): For SHORT texts (< 3 words), block ؟/!
+    # unless text contains interrogative/exclamatory cue words. For longer
+    # texts (3+ words), allow any terminal punct freely. This prevents
+    # "محمد" → "محمد؟" while still allowing "اليوم" → "اليوم.".
     TERMINAL_PUNCT = set('.,،؛؟!:;?!')
     orig_stripped = original.rstrip()
     corr_stripped = correction.rstrip()
@@ -139,33 +156,34 @@ def validate_punctuation_diff(diff: dict, full_text: str = '') -> bool:
                 if _normalize_for_comparison(orig_no_punct.replace(' ', '')) == \
                    _normalize_for_comparison(corr_no_punct.replace(' ', '')):
                     # This is a pure terminal-punctuation addition.
-                    # Decide whether to allow based on full text context.
+                    # V2 FIX-30: Fall back to original when full_text is empty
+                    _word_count_source = full_text if full_text else original
                     _full_word_count = len(re.findall(
-                        r'[\u0600-\u06FFa-zA-Z]+', full_text
-                    )) if full_text else 0
+                        r'[\u0600-\u06FFa-zA-Z]+', _word_count_source
+                    ))
                     _full_already_has_terminal = bool(
                         re.search(r'[.،؛؟!?!][\s]*$', full_text)
                     ) if full_text else False
-                    # Also check for ellipsis (... at end)
                     _full_has_ellipsis = full_text.rstrip().endswith('...') if full_text else False
 
-                    if _full_word_count >= 5 and not _full_already_has_terminal and not _full_has_ellipsis:
-                        # ── FIX-29: Exclamation mark guard ──
-                        # PuncAra sometimes adds ! to declarative sentences.
-                        # Only allow ! if text contains exclamatory cues.
+                    # V2 FIX-30: Allow for 1+ words (not 5)
+                    if _full_word_count >= 1 and not _full_already_has_terminal and not _full_has_ellipsis:
+                        # ── Softened FIX-29 (Merged): Short-text ؟/! guard ──
+                        # For short texts (< 3 words), block ؟ and ! unless
+                        # cue words are present. Prevents "محمد" → "محمد؟"
+                        # but allows "اليوم" → "اليوم." (period is safe).
+                        # For 3+ words, allow freely (V2 behavior).
                         _added_punct = correction[len(orig_stripped):]
-                        if '!' in _added_punct or '؟' in _added_punct:
-                            # Check for question/exclamation words
-                            _EXCL_CUES = {'يا', 'ما', 'كم', 'لا', 'هل', 'أين', 'متى',
-                                          'كيف', 'لماذا', 'ماذا', 'أي', 'لعل', 'ليت'}
-                            _has_cue = any(w in _EXCL_CUES for w in full_text.split())
+                        if _full_word_count < 3 and ('!' in _added_punct or '؟' in _added_punct):
+                            _text_to_scan = full_text if full_text else original
+                            _has_cue = any(w in _EXCL_CUES for w in _text_to_scan.split())
                             if not _has_cue:
                                 logger.info(
-                                    f"[PUNC-SAFETY] Blocked !/? on declarative sentence: "
+                                    f"[PUNC-SAFETY] Blocked !/؟ on short text without cue: "
                                     f"'{original}' → '{correction}'"
                                 )
                                 return False
-                        # Multi-word sentence without terminal punct → ALLOW
+
                         logger.info(
                             f"[PUNC-SAFETY] Allowed terminal punct for sentence "
                             f"({_full_word_count} words): "
@@ -173,7 +191,7 @@ def validate_punctuation_diff(diff: dict, full_text: str = '') -> bool:
                         )
                         # Fall through to remaining rules (don't return yet)
                     else:
-                        # Short fragment OR already has terminal punct → REJECT
+                        # Already has terminal punct or ends in ellipsis → REJECT
                         logger.info(
                             f"[PUNC-SAFETY] TerminalPunctuationGuard triggered: removing trailing punctuation "
                             f"'{original}' → '{correction}'"
@@ -202,9 +220,11 @@ def validate_punctuation_diff(diff: dict, full_text: str = '') -> bool:
                 return False
 
     # ── Rule 0c (Batch 4 + FIX-26): Reject punctuation rearrangement/substitution ──
-    # When original already has punctuation and the correction merely MOVES
-    # or SUBSTITUTES marks (e.g., ، → : or ، → ؛), reject.
-    # The PuncAra model should NOT replace existing punctuation.
+    # When original already has punctuation and the correction merely MOVES,
+    # SUBSTITUTES, or STACKS marks (e.g., ، → : or ، → ؛ or ؟ → ؟!), reject.
+    # The PuncAra model should NOT replace or pile onto existing punctuation —
+    # a sentence that already ends with punctuation must never get a second
+    # mark added next to it.
     orig_punct_count_r0c = sum(1 for c in original if c in ARABIC_PUNCT_CHARS)
     corr_punct_count_r0c = sum(1 for c in correction if c in ARABIC_PUNCT_CHARS)
     if orig_punct_count_r0c > 0 and corr_punct_count_r0c > 0:
@@ -212,9 +232,10 @@ def validate_punctuation_diff(diff: dict, full_text: str = '') -> bool:
         orig_alpha_r0c = re.sub(r'[.,،؛؟!:;?\s]', '', original)
         corr_alpha_r0c = re.sub(r'[.,،؛؟!:;?\s]', '', correction)
         if _normalize_for_comparison(orig_alpha_r0c) == _normalize_for_comparison(corr_alpha_r0c):
-            # Same word content, but punct changed — reject any punct modification
+            # Same word content, but punct changed — reject any punct modification,
+            # whether it's a substitution or an addition on top of existing punct.
             logger.info(
-                f"[PUNC-SAFETY] Rejected punct substitution: "
+                f"[PUNC-SAFETY] Rejected punct substitution/stacking: "
                 f"'{original}' → '{correction}'"
             )
             return False
@@ -249,4 +270,3 @@ def validate_punctuation_diff(diff: dict, full_text: str = '') -> bool:
         return False
 
     return True
-