Address PR #347 R3: sync docs to implemented aggregation tags + real-fit no-scalar test

R3 approved (✅) with two non-blocking follow-ups; this commit
addresses both.

P2 (docs): ``REPORTING.md`` and ``business_report.rst`` still
listed the obsolete dCDH aggregation tags (``"DID_l"``, ``"l"``,
``"l_x"``, ``"l_fd"``, ``"l_x_fd"``) and documented
``headline_attribute`` as always a string, even though R2 replaced
those with ``"DID_1"`` / ``"DID_1_x"`` / ``"DID_1_fd"`` /
``"DID_1_x_fd"`` / ``"delta"`` / ``"delta_x"`` /
``"no_scalar_headline"`` and introduced the
``headline_attribute=None`` no-scalar case. Consumers wiring
dispatch logic off the docs would have pointed at tags the helper
no longer emits. Rewrote the ``aggregation`` enum in REPORTING.md
as a full per-estimator dispatch list, and updated the
``headline_attribute`` description to name the ``None`` case
explicitly. ``business_report.rst`` summary replaced ``DID_l``
with ``DID_1`` / cost-benefit delta and added a pointer to the
no-scalar case.

P3 (tests): added ``test_dcdh_trends_linear_with_l_max_geq_2_fit_real``
— a real-fit regression that exercises the
``ChaisemartinDHaultfoeuille(..., L_max=2, trends_linear=True)``
path end-to-end. Asserts (a) ``fit.overall_att`` is NaN by design
(matching ``chaisemartin_dhaultfoeuille.py:2828-2834``), (b)
``linear_trends_effects`` is populated, (c) the target-parameter
block emits ``aggregation="no_scalar_headline"`` and
``headline_attribute is None``, (d) the definition references
``linear_trends_effects``. Previously this branch was only
stub-tested; now the reporting-layer integration is pinned by a
live dCDH fit.

333 BR/DR tests pass. Black and ruff clean.

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

Author: igerber

docs/api/business_report.rst

@@ -51,10 +51,16 @@ stability) are documented in :doc:`../methodology/REPORTING`.
 
 The schema carries a top-level ``target_parameter`` block
 (experimental) naming what the headline scalar represents per
-estimator — simple ATT, event-study average, DID_M, DID_l,
-dose-response aggregate, factor-model residual, etc. See the
-"Target parameter" section of :doc:`../methodology/REPORTING` for
-the per-estimator dispatch and schema shape.
+estimator — simple ATT, event-study average, DID_M, DID_1,
+cost-benefit delta, dose-response aggregate, factor-model residual,
+etc. For the dCDH dynamic branch with ``trends_linear=True`` and
+``L_max>=2``, the scalar is intentionally NaN and
+``aggregation`` is ``"no_scalar_headline"`` with
+``headline_attribute`` set to ``None`` — agents should dispatch on
+this case and consult ``linear_trends_effects`` instead of
+``overall_att``. See the "Target parameter" section of
+:doc:`../methodology/REPORTING` for the full per-estimator dispatch
+table and schema shape.
 
 Example
 -------

docs/methodology/REPORTING.md

@@ -88,15 +88,35 @@ Field semantics:
   summary paragraph so stakeholder prose stays within the 6-10-
   sentence target.
 - `aggregation` — machine-readable tag dispatching agents can
-  branch on: `"simple"`, `"event_study"`, `"group"`, `"2x2"`,
-  `"twfe"`, `"iw"`, `"stacked"`, `"ddd"`, `"staggered_ddd"`,
-  `"synthetic"`, `"factor_model"`, `"M"`, `"l"`, `"l_x"`,
-  `"l_fd"`, `"l_x_fd"`, `"dose_overall"`,
-  `"pt_all_combined"`, `"pt_post_single_baseline"`, `"unknown"`.
+  branch on. Complete enumeration per estimator:
+  - `"2x2"` (DiDResults / TwoWayFixedEffects both route here)
+  - `"event_study"` (MultiPeriodDiDResults)
+  - `"simple"` (CallawaySantAnna / Imputation / TwoStage / Wooldridge)
+  - `"iw"` (SunAbraham)
+  - `"stacked"` (StackedDiD)
+  - `"pt_all_combined"` / `"pt_post_single_baseline"` (EfficientDiD
+    branched on `pt_assumption`)
+  - `"dose_overall"` (ContinuousDiD)
+  - `"ddd"` / `"staggered_ddd"` (TripleDifference / StaggeredTripleDiff)
+  - dCDH dynamic branches follow the exact `overall_att`
+    contract: `"M"` / `"M_x"` / `"M_fd"` / `"M_x_fd"` for
+    `L_max=None`; `"DID_1"` / `"DID_1_x"` / `"DID_1_fd"` /
+    `"DID_1_x_fd"` for `L_max=1`; `"delta"` / `"delta_x"` for
+    `L_max>=2` without trend suppression; and
+    `"no_scalar_headline"` when `trends_linear=True` AND
+    `L_max>=2` (the scalar is intentionally NaN).
+  - `"synthetic"` (SyntheticDiD) / `"factor_model"` (TROP) /
+    `"twfe"` (BaconDecomposition read-out) / `"unknown"` (default
+    fallback).
 - `headline_attribute` — the raw result attribute the scalar
   comes from (`"overall_att"` / `"att"` / `"avg_att"` /
-  `"twfe_estimate"`). Different result classes use different
-  attribute names; agents that want to re-read the raw value
+  `"twfe_estimate"`), OR `None` when `aggregation ==
+  "no_scalar_headline"` (the dCDH `trends_linear=True,
+  L_max>=2` branch where `overall_att` is intentionally NaN by
+  design). Agents dispatching on this field must handle `None` as
+  "no scalar aggregate — consult `linear_trends_effects`
+  instead". Different result classes use different attribute
+  names; agents that want to re-read the raw value
   can dispatch on this.
 - `reference` — one-line citation pointer to the canonical paper
   and the REGISTRY.md section.

tests/test_target_parameter.py

@@ -588,3 +588,45 @@ def test_dcdh_delta_fit_real(self):
         assert "delta" in tp["name"]
         assert tp["headline_attribute"] == "overall_att"
         assert hasattr(fit, "overall_att")
+
+    def test_dcdh_trends_linear_with_l_max_geq_2_fit_real(self):
+        """Real ``trends_linear=True`` + ``L_max>=2`` fit: the library
+        intentionally sets ``overall_att=NaN`` and populates the
+        per-horizon effects on ``linear_trends_effects`` instead
+        (``chaisemartin_dhaultfoeuille.py:2828-2834``). The target-
+        parameter block must reflect that via
+        ``aggregation="no_scalar_headline"`` and
+        ``headline_attribute is None``. PR #347 R3 P3 regression on
+        a live fit.
+        """
+        import math
+        import warnings
+
+        from diff_diff import ChaisemartinDHaultfoeuille
+
+        warnings.filterwarnings("ignore")
+        df = self._dcdh_reversible_panel(seed=15)
+        fit = ChaisemartinDHaultfoeuille().fit(
+            df,
+            outcome="outcome",
+            group="unit",
+            time="period",
+            treatment="treated",
+            L_max=2,
+            trends_linear=True,
+        )
+        # Real fit must intentionally produce NaN overall_att.
+        assert math.isnan(fit.overall_att), (
+            "trends_linear + L_max>=2 must suppress overall_att (NaN by "
+            "design). If this test fails, the library contract changed — "
+            "update the ``no_scalar_headline`` branch of "
+            "describe_target_parameter accordingly."
+        )
+        # linear_trends_effects must be populated (the per-horizon
+        # cumulated level effects that replace the scalar aggregate).
+        assert fit.linear_trends_effects is not None
+        # Target-parameter block must route through the no-scalar branch.
+        tp = describe_target_parameter(fit)
+        assert tp["aggregation"] == "no_scalar_headline"
+        assert tp["headline_attribute"] is None
+        assert "linear_trends_effects" in tp["definition"]