feat: add multi-quarter lexicon trend detection to textdiff

Add `_detect_trend(counts)` pure helper that finds the longest strictly
monotone tail run (≥3 quarters) in a count series, and
`compute_lexicon_trend(ticker, n=4)` that applies it across all 18
_LEXICON terms over up to 4 recent 10-Q periods.

Wire into `_compute_inner` as step 5: trend signals for a term
supersede any QoQ term_frequency delta for the same term, so the
analyst never sees a redundant single-quarter spike alongside the
stronger multi-quarter narrative.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

analysis/textdiff.py

@@ -356,6 +356,143 @@ def _find_context_sentence(text: str, pattern: str) -> str:
     return ""
 
 
+# ---------------------------------------------------------------------------
+# Multi-quarter lexicon trend detection
+# ---------------------------------------------------------------------------
+
+def _detect_trend(counts: list[int]) -> str | None:
+    """Detect the longest strictly monotone run at the tail of a count series.
+
+    Args:
+        counts: term occurrence counts in **chronological order** (oldest first).
+
+    Returns:
+        ``"rising N quarters"`` if the last N≥3 values are strictly increasing,
+        ``"falling N quarters"`` if the last N≥3 values are strictly decreasing,
+        ``None`` otherwise.
+
+    Examples:
+        >>> _detect_trend([1, 3, 5, 8])
+        'rising 4 quarters'
+        >>> _detect_trend([8, 5, 3, 1])
+        'falling 4 quarters'
+        >>> _detect_trend([1, 5, 2, 4, 6])
+        'rising 3 quarters'
+        >>> _detect_trend([1, 2, 2, 4])  # plateau breaks strict run
+        >>> _detect_trend([1, 3])  # only 2 values
+    """
+    if len(counts) < 2:
+        return None
+
+    # Walk backwards from the end to find the longest tail run
+    # We track whether the tail is rising or falling from the last step
+    n = len(counts)
+
+    # Determine direction of the final step
+    if counts[-1] > counts[-2]:
+        direction = "rising"
+    elif counts[-1] < counts[-2]:
+        direction = "falling"
+    else:
+        return None  # last step is flat → no strict run
+
+    # Extend the run backwards as far as the same strict direction holds
+    run_length = 2  # we already know the last pair qualifies
+    for i in range(n - 2, 0, -1):
+        if direction == "rising" and counts[i] > counts[i - 1]:
+            run_length += 1
+        elif direction == "falling" and counts[i] < counts[i - 1]:
+            run_length += 1
+        else:
+            break  # run ends here
+
+    if run_length < 3:
+        return None
+
+    return f"{direction} {run_length} quarters"
+
+
+def compute_lexicon_trend(ticker: str, n: int = 4) -> list[QuarterDelta]:
+    """Detect multi-quarter monotone trends for each analyst-lexicon term.
+
+    Looks back up to *n* 10-Q periods and surfaces terms whose occurrence
+    count has been strictly rising or falling for 3+ consecutive quarters —
+    a more durable signal than a single quarter-over-quarter spike.
+
+    Args:
+        ticker: uppercase ticker symbol.
+        n: maximum number of recent 10-Q periods to examine (default 4).
+
+    Returns:
+        Up to 5 ``QuarterDelta`` objects (HIGH-significance first), one per
+        term that shows a multi-quarter trend.  Returns ``[]`` if fewer than
+        3 periods are available or no trends are detected.
+    """
+    ticker = ticker.upper()
+    periods = get_periods_for_ticker(ticker, form_type="10-Q")
+    if len(periods) < 3:
+        return []
+
+    n = min(n, len(periods))
+    # periods[:n] is newest-first; reverse for chronological order
+    selected = list(reversed(periods[:n]))  # [oldest, ..., newest]
+
+    # Pre-load section text for each period
+    period_texts: list[str] = []
+    for period in selected:
+        mda = get_section(ticker, period, "mda") or ""
+        risk = get_section(ticker, period, "risk_factors") or ""
+        period_texts.append((mda + "\n\n" + risk).strip())
+
+    deltas: list[QuarterDelta] = []
+
+    for pattern, label in _LEXICON:
+        counts = [
+            len(re.findall(pattern, text, re.IGNORECASE))
+            for text in period_texts
+        ]
+
+        trend = _detect_trend(counts)
+        if trend is None:
+            continue
+
+        # Build the QuarterDelta
+        oldest_period = selected[0]   # periods[n-1] in newest-first order
+        newest_period = selected[-1]  # periods[0]
+
+        first_count = counts[0]
+        last_count = counts[-1]
+        metric = (
+            f"{first_count}→{last_count} occurrences over "
+            f"{oldest_period}→{newest_period} ({trend})"
+        )
+
+        oldest_text = period_texts[0]
+        newest_text = period_texts[-1]
+        before_ctx = _find_context_sentence(oldest_text, pattern) if first_count > 0 else ""
+        after_ctx = _find_context_sentence(newest_text, pattern) if last_count > 0 else ""
+
+        # Significance: HIGH for runs of 4+, MEDIUM for 3
+        run_quarters = int(trend.split()[1])
+        sig = "HIGH" if run_quarters >= 4 else "MEDIUM"
+
+        deltas.append(QuarterDelta(
+            kind="term_frequency",
+            period_from=oldest_period,
+            period_to=newest_period,
+            before_text=before_ctx,
+            after_text=after_ctx,
+            computed_metric=metric,
+            source="10-Q",
+            significance=sig,
+            term=label,
+        ))
+
+    # HIGH first, then MEDIUM; cap at 5
+    deltas.sort(key=lambda d: {"HIGH": 0, "MEDIUM": 1}.get(d.significance, 2))
+    return deltas[:5]
+
+
 # ---------------------------------------------------------------------------
 # Guidance / MD&A language shift
 # ---------------------------------------------------------------------------
@@ -568,6 +705,28 @@ def _compute_inner(ticker: str, current_period: Optional[str]) -> list[QuarterDe
     if cur_mda and pri_mda:
         all_deltas.extend(compute_kpi_drops(cur_mda, pri_mda, period_from, period_to, form_type))
 
+    # 5. Multi-quarter lexicon trends (ticker-level, not period-pair)
+    trend_deltas = compute_lexicon_trend(ticker)
+    all_deltas.extend(trend_deltas)
+
+    # Prefer trend signals over QoQ signals for the same term:
+    # collect terms that have a multi-quarter trend signal and remove any
+    # plain QoQ term_frequency delta for the same term.
+    trend_terms: set[str] = {
+        d.term
+        for d in trend_deltas
+        if d.kind == "term_frequency" and "quarters" in (d.computed_metric or "")
+    }
+    if trend_terms:
+        all_deltas = [
+            d for d in all_deltas
+            if not (
+                d.kind == "term_frequency"
+                and d.term in trend_terms
+                and "quarters" not in (d.computed_metric or "")
+            )
+        ]
+
     # Deduplicate and sort: HIGH first, then MEDIUM, then LOW
     seen: set[str] = set()
     deduped: list[QuarterDelta] = []