Address CI R14 (P2 + P3) on PreTrendsPower PR-B

R14 verdict ✅ Looks good with one P2 BR-schema-gap + a P3 fan-out
of stale "MDV vs ATT" prose that the R12 level-scale fix needed to
sweep through but missed.

**P2 — `_lift_pre_trends` dropped `max_abs_pre_violation`**

R12 added `max_abs_pre_violation` to the `DiagnosticReport` schema
and wired the `BusinessReport.full_report()` renderer to print it,
but the BR schema-lift helper at `business_report.py:884` did NOT
carry the field across the DR → BR boundary. Net effect:
`BR.to_dict()["pre_trends"]` was missing the field AND
`full_report()`'s `pt.get("max_abs_pre_violation")` returned None,
so the new "Max pre-period level deviation at MDV" line never
actually rendered.

Fix: add `"max_abs_pre_violation": pp.get("max_abs_pre_violation")`
to the `_lift_pre_trends` return dict. New BR end-to-end regression
asserts both `BR.to_dict()["pre_trends"]["max_abs_pre_violation"]`
is populated AND `full_report()` contains the rendered line.

**P3 — Stale "MDV / |ATT|" prose in 4 surfaces**

R12 moved the tier numerator from raw `mdv` to `max_abs_pre_violation`
but several user-facing prose surfaces still said the comparison
was between "MDV" and "estimated effect" — wording lag, not a
behavioral bug.

1. `business_report.py:2167` "the test is well-powered" summary
   sentence: reworded to say "the max pre-period level deviation at
   the MDV is small relative to the estimated effect" rather than
   the bare "minimum-detectable violation is small".
2. `diagnostic_report.py:3284` DR "no_detected_violation /
   well_powered" sentence: same swap from "MDV is a small share of
   the estimated effect" to "the max pre-period level deviation at
   the MDV is a small share".
3. `PreTrendsPowerResults.violation_weights` docstring: reworded to
   enumerate per-violation_type normalization explicitly (linear
   with-times γ-unit; linear legacy L2-norm; constant unnormalized
   level-shift; last_period level; custom L2-norm).
4. `PreTrendsPowerResults.max_abs_pre_violation` property docstring
   (the non-linear-types paragraph): updated to reflect the R13
   constant-level-shift change (`mdv * 1 = mdv` rather than the old
   `mdv / √K`).

Plus the autosummary RST adds the new
`~PreTrendsPowerResults.max_abs_pre_violation` property entry so
the published API page lists it.

R-parity P3 deferred to PR-C per the existing TODO row.

591 tests pass; no code-path regressions. The new BR regression
catches the lift-boundary bug if it ever regresses.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: igerber

diff_diff/business_report.py

@@ -924,6 +924,13 @@ def _lift_pre_trends(dr: Optional[Dict[str, Any]]) -> Dict[str, Any]:
         "power_reason": pp.get("reason"),
         "power_tier": pp.get("tier"),
         "mdv": pp.get("mdv"),
+        # Level-scale max pre-period violation under the MDV
+        # (PR-B R12: `mdv * max(|violation_weights|)`). Carried alongside
+        # the raw `mdv` so BR schema consumers and the full-report
+        # renderer can show both quantities. Pre-R14 this was silently
+        # dropped at the BR lift boundary so the new renderer line never
+        # fired even though DR emitted the value.
+        "max_abs_pre_violation": pp.get("max_abs_pre_violation"),
         "mdv_share_of_att": pp.get("mdv_share_of_att"),
         # Carry the covariance-source annotation through so BR can hedge the
         # power-tier phrasing when compute_pretrends_power silently used a
@@ -2158,8 +2165,9 @@ def _render_summary(schema: Dict[str, Any]) -> str:
             if tier == "well_powered":
                 sentences.append(
                     f"{subject} are consistent with parallel trends, and "
-                    "the test is well-powered (the minimum-detectable "
-                    "violation is small relative to the estimated effect)."
+                    "the test is well-powered (the max pre-period level "
+                    "deviation at the MDV is small relative to the "
+                    "estimated effect)."
                 )
             elif tier == "moderately_powered":
                 sentences.append(

diff_diff/diagnostic_report.py

@@ -3281,9 +3281,10 @@ def _render_overall_interpretation(schema: Dict[str, Any], labels: Dict[str, str
             if tier == "well_powered":
                 sentences.append(
                     f"{subject} are consistent with parallel trends"
-                    f"{jp_str} and the test is well-powered (MDV is a small "
-                    "share of the estimated effect), so a material pre-trend "
-                    "would likely have been detected."
+                    f"{jp_str} and the test is well-powered (the max pre-period "
+                    "level deviation at the MDV is a small share of the estimated "
+                    "effect), so a material pre-trend would likely have been "
+                    "detected."
                 )
             elif tier == "moderately_powered":
                 sentences.append(

diff_diff/pretrends.py

@@ -288,12 +288,19 @@ class PreTrendsPowerResults:
         alternative ``M * weights``. NIS-only; NaN for Wald fits.
     violation_weights : np.ndarray, optional
         The violation-direction vector used at fit time. Populated for all
-        violation types on fresh fits. Normalization depends on the type:
-        ``constant`` / ``last_period`` / ``custom`` (or ``linear`` without
-        ``relative_times``) are stored L2-normalized; ``linear`` threaded
-        with ``relative_times`` (the post-PR-B Step 4 γ-unit path)
-        intentionally persists the unnormalized ``|t|`` direction so that
-        ``δ_pre = M · |t|`` and the reported MDV equals Roth's γ exactly.
+        violation types on fresh fits. Normalization depends on the type
+        so that ``M`` always matches the documented per-pattern contract:
+
+        - ``linear`` threaded with ``relative_times`` (post PR-B Step 4):
+          ``|t|`` directly, NOT L2-normalized, so ``δ_t = M·|t|`` and the
+          reported MDV equals Roth's γ exactly.
+        - ``linear`` without ``relative_times`` (legacy):
+          ``[n_pre-1, ..., 0]`` L2-normalized.
+        - ``constant`` (post PR-B R13): ``[1, ..., 1]`` directly, NOT
+          L2-normalized, so ``δ_t = M`` is a true per-period level shift.
+        - ``last_period``: ``[0, ..., 0, 1]`` (already unit-norm).
+        - ``custom``: user vector L2-normalized to unit norm.
+
         Old serialized results may have ``None`` here; ``power_at()``
         falls back to reconstruction in that case (with the PR-A
         ``NotImplementedError`` guard retained only for
@@ -367,10 +374,14 @@ def max_abs_pre_violation(self) -> float:
         alone cannot be compared to level effects without applying
         the weight scale.
 
-        For non-linear violation types: constant weights ``[1/√K, ...,
-        1/√K]`` yield ``max_abs_pre_violation = mdv / √K``;
-        last_period ``[0, ..., 0, 1]`` yields ``max_abs_pre_violation
-        = mdv``; custom uses the user-supplied weight vector.
+        For non-linear violation types under the PR-B R13 level-shift
+        convention: constant weights ``[1, ..., 1]`` (unnormalized)
+        yield ``max_abs_pre_violation = mdv * 1 = mdv`` — raw ``mdv``
+        IS the per-period level shift, so level- and γ-scales coincide.
+        Last_period ``[0, ..., 0, 1]`` yields ``max_abs_pre_violation
+        = mdv`` for the same reason. Custom uses the L2-normalized
+        user-supplied weight vector, so ``max_abs_pre_violation``
+        depends on the user's direction.
 
         Backwards-compat: legacy serialized results without
         ``violation_weights`` (pre-PR-B) fall back to the raw ``mdv``

docs/api/_autosummary/diff_diff.PreTrendsPowerResults.rst

@@ -26,6 +26,7 @@
    .. autosummary::
 
       ~PreTrendsPowerResults.is_informative
+      ~PreTrendsPowerResults.max_abs_pre_violation
       ~PreTrendsPowerResults.original_results
       ~PreTrendsPowerResults.power_adequate
       ~PreTrendsPowerResults.power

tests/test_business_report.py

@@ -2506,6 +2506,27 @@ def test_full_vcov_path_no_downgrade_on_real_cs_fit(self, cs_fit):
         assert "moderately informative" not in full.lower()
         assert "moderately-informative" not in full.lower()
 
+        # PR-B R14 P2: max_abs_pre_violation must round-trip through the
+        # BR schema lift AND render in full_report(). Pre-R14 the field
+        # was emitted by DR, the renderer printed it, but the BR lift
+        # boundary at `_lift_pre_trends` silently dropped it — so the
+        # rendered line never fired even though the renderer had the
+        # branch.
+        br_schema = br.to_dict()
+        pt_block = br_schema.get("pre_trends", {})
+        assert "max_abs_pre_violation" in pt_block, (
+            "BR.to_dict()['pre_trends'] must surface max_abs_pre_violation "
+            "post-PR-B R14 — _lift_pre_trends regression"
+        )
+        assert pt_block["max_abs_pre_violation"] is not None
+        assert np.isclose(pt_block["max_abs_pre_violation"], 0.375, atol=0.05)
+        # full_report() must render the new "Max pre-period level
+        # deviation at MDV" line.
+        assert "Max pre-period level deviation at MDV:" in full, (
+            "BR.full_report() must render the max_abs_pre_violation line "
+            "(renderer wired in R12; lift boundary fixed in R14)"
+        )
+
 
 class TestCSNotYetTreatedControlGroupSemantics:
     """Round-13 P1 regression: ``BusinessReport`` must not relabel