docs: HAD ecosystem completion (RTD audit Batch A)

Closes the gaps left after PR igerber#372 added HeterogeneousAdoptionDiD to the
canonical surfaces. The narrative pages did not yet mention HAD, and the
12-symbol HAD pretest suite shipped in `had_pretests.py` was absent from
the API page. Also refreshes the inference-contract block to use the
`survey_design=` canonical kwarg consolidated in PR igerber#376.

- `docs/api/had.rst`: new HAD Pretests section covering all 12 public
  symbols (4 single-period tests + 4 result classes + 3 joint tests + 1
  joint result), split into `aggregate="overall"` and
  `aggregate="event_study"` subsections matching the workflow's dispatch.
  Refreshes the existing inference-contract block to reference
  `survey_design=make_pweight_design(weights)` (pweight shortcut) and
  `survey_design=SurveyDesign(...)` (full TSL); notes `survey=` /
  `weights=` are deprecated aliases.
- `docs/choosing_estimator.rst`: HAD entries in all 3 tables (Quick
  Reference, Standard Error Methods, Survey Design Support) plus a new
  "Universal Rollout / No Untreated Control" subsection in Detailed
  Guidance. SE Methods row uses `survey_design=` canonical naming.
- `docs/r_comparison.rst`: HAD row in Feature Comparison Table, new
  "No-Untreated Designs (no R parallel)" subsection, Migration Tips
  bullet.
- `docs/troubleshooting.rst`: new HAD Issues section with 4 subsections
  (estimand resolution / mass-point fallback / classical SE under
  survey_design / panel-only event-study).
- `docs/practitioner_decision_tree.rst`: Start Here option 7, At a
  Glance row, new "Universal Rollout" section with `_section-no-untreated`
  anchor.
- `docs/doc-deps.yaml`: extend had_pretests.py entry with llms.txt
  user-guide dep; add new top-level local_linear.py entry.

Verification: all 12 HAD pretest symbols importable; `make_pweight_design`
+ `SurveyDesign` importable; sphinx build succeeds with 0 new warnings
(71 pre-existing unaffected); HTML render contains expected HAD content
(276 hits in had.html, 4-8 in narrative pages); 0 em dashes;
`_section-no-untreated` anchor resolves.

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

Author: igerber

docs/api/had.rst

@@ -46,20 +46,27 @@ Unit Remains Untreated" (arXiv:2405.04465v6), which:
    - **Unweighted** - continuous paths use the CCT-2014 weighted-robust SE
      from the in-house ``lprobust`` port; the mass-point path uses a
      structural-residual 2SLS sandwich. No cross-horizon covariance.
-   - **``weights=`` shortcut** - continuous paths reuse the CCT-2014 SE;
-     the mass-point path uses an analytical weighted 2SLS sandwich
-     (``classical`` / ``hc1`` only - ``hc2`` / ``hc2_bm`` raise
-     ``NotImplementedError`` pending a 2SLS-specific leverage derivation).
-   - **``survey=``** - both paths compose Binder (1983) Taylor-series
-     linearization with ``df_survey`` threaded into ``safe_inference``.
+   - **``survey_design=make_pweight_design(weights)``** (pweight-only
+     shortcut) - continuous paths reuse the CCT-2014 SE; the mass-point
+     path uses an analytical weighted 2SLS sandwich (``classical`` /
+     ``hc1`` only - ``hc2`` / ``hc2_bm`` raise ``NotImplementedError``
+     pending a 2SLS-specific leverage derivation).
+   - **``survey_design=SurveyDesign(...)``** (full TSL with strata / PSU
+     / FPC) - both paths compose Binder (1983) Taylor-series linearization
+     with ``df_survey`` threaded into ``safe_inference``.
+
+   The deprecated ``survey=`` and ``weights=`` aliases still resolve to
+   the same paths with a ``DeprecationWarning`` (removal queued for the
+   next minor release).
 
    A simultaneous confidence band (sup-t) is available only on the
    **weighted event-study path** via ``cband=True``. Joint cross-horizon
    analytical covariance is not computed in this release; tracked in
    ``TODO.md``.
 
    **Mass-point ``vcov_type="classical"`` deviation.** The mass-point
-   ``survey=`` paths (static and event-study) and the ``weights=`` +
+   ``survey_design=SurveyDesign(...)`` paths (static and event-study) and
+   the ``survey_design=make_pweight_design(weights)`` +
    ``aggregate="event_study"`` + ``cband=True`` path reject
    ``vcov_type="classical"`` with ``NotImplementedError``. The per-unit
    2SLS influence function returned by the mass-point fit is HC1-scaled
@@ -97,3 +104,59 @@ Multi-period event-study results container for the Appendix B.2 extension.
    :members:
    :undoc-members:
    :show-inheritance:
+
+HAD Pretests
+------------
+
+Diagnostic pretests for the HAD identification assumptions from de Chaisemartin
+et al. (2026). The composite orchestrator
+:func:`~diff_diff.did_had_pretest_workflow` dispatches to two shapes based on
+panel structure: the **overall** path (two-period first-differenced sample)
+runs single-period tests; the **event-study** path (three or more periods)
+runs joint multi-period tests. Both paths return a unified
+:class:`~diff_diff.HADPretestReport`.
+
+.. autofunction:: diff_diff.did_had_pretest_workflow
+
+.. autoclass:: diff_diff.HADPretestReport
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Single-period tests (``aggregate="overall"``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autofunction:: diff_diff.qug_test
+
+.. autofunction:: diff_diff.stute_test
+
+.. autofunction:: diff_diff.yatchew_hr_test
+
+.. autoclass:: diff_diff.QUGTestResults
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: diff_diff.StuteTestResults
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: diff_diff.YatchewTestResults
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Joint multi-period tests (``aggregate="event_study"``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autofunction:: diff_diff.stute_joint_pretest
+
+.. autofunction:: diff_diff.joint_pretrends_test
+
+.. autofunction:: diff_diff.joint_homogeneity_test
+
+.. autoclass:: diff_diff.StuteJointResult
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/choosing_estimator.rst

@@ -93,6 +93,10 @@ Quick Reference
      - Continuous dose / treatment intensity
      - Strong Parallel Trends (SPT) for dose-response; PT for binarized ATT
      - ATT\ :sup:`loc` (PT); ATT(d), ACRT(d) (SPT)
+   * - ``HeterogeneousAdoptionDiD``
+     - Universal rollout, dose varies, no untreated unit
+     - dCDH 2026 Assumptions (Design 1' QUG case or Design 1 with A6/A5)
+     - WAS or WAS\ :sub:`d_lower` per resolved estimand; event-study Appendix B.2
    * - ``SunAbraham``
      - Staggered adoption, interaction-weighted
      - Conditional parallel trends
@@ -357,6 +361,49 @@ Use :class:`~diff_diff.ContinuousDiD` when:
    print(f"Overall ATT: {results.overall_att:.3f}")
    att_curve = results.dose_response_att.to_dataframe()
 
+Universal Rollout / No Untreated Control
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use :class:`~diff_diff.HeterogeneousAdoptionDiD` when:
+
+- **Every unit is treated at the post period** (universal-rollout policy,
+  industry-wide tariff change, simultaneous launch into all markets)
+- Treatment **intensity (dose) varies across units**, but no genuinely
+  untreated control group exists to anchor a standard DiD contrast
+- :class:`~diff_diff.ContinuousDiD` is unavailable because its untreated-group
+  requirement (``D = 0``) is violated
+
+The estimator implements de Chaisemartin, Ciccia, D'Haultfoeuille and Knau
+(2026, arXiv:2405.04465v6) and resolves to one of two estimands depending on
+the dose support:
+
+- **Design 1' (QUG case, ``d_lower = 0``)** identifies the **Weighted Average
+  Slope (WAS)** under the Quasi-Untreated-Group assumption (units with the
+  smallest dose serve as the comparison anchor). The shipped result class
+  exposes ``target_parameter == "WAS"``.
+- **Design 1 (no QUG, ``d_lower > 0``)** identifies ``WAS_{d_lower}`` under
+  Assumption 6, or sign identification only under Assumption 5; neither
+  additional assumption is testable via pre-trends. Result class exposes
+  ``target_parameter == "WAS_d_lower"``.
+
+The dose-distribution path is auto-detected. Run
+:func:`~diff_diff.did_had_pretest_workflow` to vet the identifying assumptions
+before estimation; see :doc:`api/had` for the full API and SE-regime contract.
+
+.. code-block:: python
+
+   from diff_diff import HeterogeneousAdoptionDiD, did_had_pretest_workflow
+
+   pretests = did_had_pretest_workflow(data, outcome='y', unit='unit',
+                                       time='period', dose='dose')
+
+   est = HeterogeneousAdoptionDiD()
+   results = est.fit(data, outcome='y', unit='unit',
+                     time='period', dose='dose')
+
+   print(f"Resolved estimand: {results.target_parameter}")
+   print(f"Estimate: {results.coef:.3f}")
+
 Efficient DiD
 ~~~~~~~~~~~~~
 
@@ -615,6 +662,9 @@ differences helps interpret results and choose appropriate inference.
    * - ``ContinuousDiD``
      - Analytical (influence function)
      - Uses influence-function-based SEs by default. Use ``n_bootstrap=199`` (or higher) for multiplier bootstrap inference with proper CIs.
+   * - ``HeterogeneousAdoptionDiD``
+     - Path-dependent (CCT-2014 / 2SLS / Binder TSL)
+     - Three SE regimes per :doc:`api/had`. **Unweighted**: continuous-dose paths use the CCT-2014 weighted-robust SE from the in-house ``lprobust`` port; mass-point uses a 2SLS sandwich. **``survey_design=make_pweight_design(weights)``** (pweight shortcut): continuous reuses CCT-2014; mass-point uses analytical weighted 2SLS (``classical`` / ``hc1`` only). **``survey_design=SurveyDesign(...)``** (full TSL): both paths compose Binder (1983) Taylor-series linearization. Per-horizon CIs are pointwise; sup-t bands available only on the weighted event-study path via ``cband=True``. The deprecated ``survey=`` / ``weights=`` aliases still resolve with a DeprecationWarning.
    * - ``SunAbraham``
      - Cluster-robust (unit level)
      - Clusters at unit level by default. Specify ``cluster`` to override. Use ``n_bootstrap`` for pairs bootstrap inference.
@@ -777,6 +827,11 @@ estimation. The depth of support varies by estimator:
      - Full
      - Full (analytical)
      - Multiplier at PSU
+   * - ``HeterogeneousAdoptionDiD``
+     - pweight only
+     - Full (Binder TSL)
+     - --
+     - Multiplier (event-study, ``cband=True`` only)
    * - ``EfficientDiD``
      - Full
      - Full

docs/doc-deps.yaml

@@ -385,6 +385,19 @@ sources:
 
   diff_diff/had_pretests.py:
     drift_risk: medium
+    docs:
+      - path: docs/methodology/REGISTRY.md
+        section: "HeterogeneousAdoptionDiD"
+        type: methodology
+      - path: docs/api/had.rst
+        section: "HAD Pretests"
+        type: api_reference
+      - path: diff_diff/guides/llms.txt
+        section: "Estimators"
+        type: user_guide
+
+  diff_diff/local_linear.py:
+    drift_risk: low
     docs:
       - path: docs/methodology/REGISTRY.md
         section: "HeterogeneousAdoptionDiD"

docs/practitioner_decision_tree.rst

@@ -44,6 +44,11 @@ Which of these best describes your situation?
    Your outcome comes from a survey with complex sampling. Go to
    :ref:`section-survey`.
 
+7. **All my markets received the campaign at the same time, but spend levels varied** (no untreated control market exists)
+
+   Universal rollout with dose-only variation. Go to
+   :ref:`section-no-untreated`.
+
 .. tip::
 
    In academic literature, "rolling out in waves" is called *staggered adoption*,
@@ -258,6 +263,51 @@ appropriate identification assumptions in place.
    require Strong Parallel Trends (see warning above).
 
 
+.. _section-no-untreated:
+
+Universal Rollout (No Untreated Markets)
+----------------------------------------
+
+**Your situation:** Every market got the campaign at the same time - there is no
+holdout group - but spending levels varied across markets. ``ContinuousDiD`` cannot
+help here because it requires an untreated comparison group; standard DiD has no
+control to anchor the contrast.
+
+**Recommended method:** :class:`~diff_diff.HeterogeneousAdoptionDiD`
+
+This estimator implements de Chaisemartin, Ciccia, D'Haultfoeuille and Knau (2026)
+and resolves to one of two estimands depending on whether the smallest-dose
+markets can serve as a quasi-untreated anchor (Design 1') or whether the
+identification rests on stronger structural assumptions (Design 1).
+
+.. code-block:: python
+
+   from diff_diff import HeterogeneousAdoptionDiD, did_had_pretest_workflow
+
+   # Run the pretest workflow first - it adjudicates which design path
+   # your data supports and surfaces assumption violations
+   pretests = did_had_pretest_workflow(
+       data, outcome="y", unit="unit", time="period", dose="dose",
+   )
+   print(pretests)
+
+   est = HeterogeneousAdoptionDiD()
+   results = est.fit(
+       data, outcome="y", unit="unit", time="period", dose="dose",
+   )
+   print(f"Resolved estimand: {results.target_parameter}")
+   print(f"Average lift per unit of dose: {results.coef:.2f}")
+
+.. note::
+
+   **Academic term:** The estimator targets the *Weighted Average Slope (WAS)* under
+   the QUG / Design 1' case, or *WAS_{d_lower}* under Design 1. Neither identifying
+   assumption is testable via pre-trends alone - run
+   :func:`~diff_diff.did_had_pretest_workflow` for the recommended battery. See
+   :doc:`api/had` for the inference contract (three SE regimes; pointwise CIs;
+   sup-t bands only on the weighted event-study path).
+
+
 .. _section-few-markets:
 
 Few Test Markets
@@ -377,6 +427,9 @@ At a Glance
    * - Varied spending levels
      - ``ContinuousDiD``
      - Dose-response curve
+   * - Universal rollout, no untreated markets
+     - ``HeterogeneousAdoptionDiD``
+     - Targets WAS / WAS_{d_lower} when no holdout exists
    * - Only a few test markets
      - ``SyntheticDiD``
      - Optimal with few treated units

docs/r_comparison.rst

@@ -213,6 +213,30 @@ The synthdid package implements Arkhangelsky et al. (2021):
        post_periods=post_periods
    )
 
+No-Untreated Designs (no R parallel)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When every unit is treated at the post period (universal-rollout policies,
+industry-wide regime changes) but treatment intensity varies across units,
+the standard R DiD ecosystem has no direct entry point - ``did``, ``fixest``,
+``synthdid``, and ``DIDmultiplegtDYN`` all assume an untreated comparison
+group exists. ``diff-diff`` ships
+:class:`~diff_diff.HeterogeneousAdoptionDiD`, which implements
+de Chaisemartin, Ciccia, D'Haultfoeuille and Knau (2026, arXiv:2405.04465v6).
+The estimator targets the Weighted Average Slope (WAS) when the smallest
+dose serves as a quasi-untreated anchor (Design 1') or ``WAS_{d_lower}``
+otherwise (Design 1, requiring Assumption 6 or sign-only Assumption 5).
+The dCDH 2026 paper has not yet been packaged in R, so this is a
+methodology niche covered in Python first.
+
+.. code-block:: python
+
+   from diff_diff import HeterogeneousAdoptionDiD
+
+   est = HeterogeneousAdoptionDiD()
+   results = est.fit(data, outcome='y', unit='unit',
+                     time='period', dose='dose')
+
 Key Differences
 ---------------
 
@@ -372,6 +396,11 @@ Feature Comparison Table
      - ❌
      - ❌
      - ❌
+   * - Heterogeneous adoption / no-untreated designs
+     - ✅
+     - ❌
+     - ❌
+     - ❌
 
 .. note::
 
@@ -382,7 +411,8 @@ Feature Comparison Table
    Stacked DiD requires manual implementation or the ``stackedev`` package;
    Continuous DiD is available via the ``did`` package continuous extension;
    Triple Difference requires manual implementation in R.
-   TROP and Efficient DiD have no direct R equivalents.
+   TROP, Efficient DiD, and HeterogeneousAdoptionDiD (dCDH 2026, the
+   no-untreated-control design) have no direct R equivalents.
 
 Migration Tips
 --------------
@@ -399,3 +429,9 @@ Migration Tips
 
 5. **Missing data**: diff-diff requires complete data; use ``balance_panel()``
    or ``dropna()`` first
+
+6. **No-untreated designs**: If your R workflow stalls because every unit was
+   treated at the post period (universal rollout, dose-only variation), reach
+   for :class:`~diff_diff.HeterogeneousAdoptionDiD`. See the
+   `No-Untreated Designs (no R parallel)`_ section above for the migration
+   pattern.

docs/references.rst

@@ -66,7 +66,7 @@ Survey-Design Inference (Taylor-Series Linearization)
 
 - **Binder, D. A. (1983).** "On the Variances of Asymptotically Normal Estimators from Complex Surveys." *International Statistical Review*, 51(3), 279-292. https://doi.org/10.2307/1402588
 
-  Foundational TSL (Taylor-Series Linearization) variance derivation used across diff-diff's survey-aware estimators (``compute_survey_if_variance`` and the per-estimator influence-function compositions, including the dCDH and HeterogeneousAdoptionDiD ``survey=`` paths).
+  Foundational TSL (Taylor-Series Linearization) variance derivation used across diff-diff's survey-aware estimators (``compute_survey_if_variance`` and the per-estimator influence-function compositions, including the dCDH and HeterogeneousAdoptionDiD ``survey_design=`` paths).
 
 Placebo Tests and DiD Diagnostics
 ---------------------------------