Address PR #389 R2 (2 P1 + 1 P2): qug_test scope, design-detection rule, DIDHAD claim

P1 (qug_test in array-in pretest helper list): `docs/api/had.rst:67-72`
listed `qug_test` alongside `stute_test` / `yatchew_hr_test` /
`stute_joint_pretest` as accepting `survey_design=make_pweight_design(weights)`.
Per `had_pretests.py:1236-1255` and the methodology REGISTRY (Phase 4.5 C0
decision gate), `qug_test` permanently raises `NotImplementedError` on any
of `survey_design=` / `survey=` / `weights=` - there is no migration target
for survey-aware QUG, and `make_pweight_design()` is explicitly NOT a valid
QUG migration target. The composite workflow `did_had_pretest_workflow`
handles weighted dispatch by skipping QUG with a `UserWarning`. Removed
`qug_test` from the array-in helper list and added an explicit
permanent-rejection note pointing to the workflow's skip behavior.

P1 (estimand-resolution rule misstatement): `docs/troubleshooting.rst`
"Resolved estimand" subsection said "no exact `dose == 0` => Design 1".
Per `had.py:1932-1987` `_detect_design()` resolves to Design 1' when EITHER
`d.min() == 0` OR `d.min() < 0.01 * median(|d|)` (small-share-of-treated
escape clause). Rewrote the cause to spell out both sub-cases and clarify
that Design 1 only fires when `d.min()` is meaningfully positive relative
to the dose scale. Updated the inspection snippet to compute and print the
`0.01 * median(|d|)` threshold instead of just counting `dose == 0` rows.

P2 (DIDHAD event-study overstatement): `docs/r_comparison.rst` Heterogeneous
Adoption section, R-equivalents note, and Migration Tips bullet claimed
diff-diff additionally covers "the multi-period event-study extension
(paper Appendix B.2)" beyond `DIDHAD`. The `DIDHAD` package already
exposes dynamic effects / placebo / event-study output in the QUG case, so
this overstates the gap. Narrowed all three locations to the documented
differences: Design 1 (no QUG, `WAS_{d_lower}`) and survey-design
integration via Binder TSL.

Sphinx build clean (0 warnings in edited files; the unrelated
`tutorials/18_geo_experiments.ipynb:61` "File not found:
practitioner_decision_tree.html#few-test-markets" warning is pre-existing
on origin/main and not introduced here).

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

Author: igerber

docs/api/had.rst

@@ -65,11 +65,16 @@ Unit Remains Untreated" (arXiv:2405.04465v6), which:
    single SE contract under ``survey_design=`` lands. (Tracked in
    ``TODO.md``; the deprecation warning emitted by ``HeterogeneousAdoptionDiD.fit``
    spells the migration out per call site.) On array-in HAD pretest
-   helpers (``stute_test``, ``yatchew_hr_test``, ``stute_joint_pretest``,
-   ``qug_test``) the pweight-only shortcut is
+   helpers (``stute_test``, ``yatchew_hr_test``, ``stute_joint_pretest``)
+   the pweight-only shortcut is
    ``survey_design=make_pweight_design(weights)``; data-in surfaces use
    ``survey_design=SurveyDesign(weights="col_name", ...)`` against
-   ``data`` instead.
+   ``data`` instead. ``qug_test`` is the exception: the QUG step has no
+   survey-aware migration target (Phase 4.5 C0 decision; see methodology
+   REGISTRY) and permanently raises ``NotImplementedError`` on any of
+   ``survey_design=`` / ``survey=`` / ``weights=``. The composite
+   workflow ``did_had_pretest_workflow`` handles this by skipping QUG
+   under survey/weighted dispatch and emitting a ``UserWarning``.
 
    A simultaneous confidence band (sup-t) is available only on the
    **weighted event-study path** via ``cband=True``. Joint cross-horizon

docs/r_comparison.rst

@@ -225,14 +225,14 @@ August 2025) covers the QUG case (Design 1', ``d_lower = 0``) from the
 same arXiv paper.
 
 ``diff-diff`` ships :class:`~diff_diff.HeterogeneousAdoptionDiD`, which
-implements the broader surface of de Chaisemartin, Ciccia, D'Haultfoeuille
-and Knau (2026, arXiv:2405.04465v6): both Design 1' (QUG case, targets
-**WAS**) **and** Design 1 (no QUG, ``d_lower > 0``, targets
-``WAS_{d_lower}`` under Assumption 6 or sign-only under Assumption 5), the
-multi-period event-study extension (paper Appendix B.2), and survey-design
-integration via Binder (1983) Taylor-series linearization. The pretest
-battery :func:`~diff_diff.did_had_pretest_workflow` adjudicates the design
-path and surfaces assumption violations.
+implements de Chaisemartin, Ciccia, D'Haultfoeuille and Knau (2026,
+arXiv:2405.04465v6) and adds two surfaces beyond the QUG-focused R
+package: Design 1 (no QUG, ``d_lower > 0``, targets ``WAS_{d_lower}`` under
+Assumption 6 or sign-only under Assumption 5), and survey-design
+integration via Binder (1983) Taylor-series linearization (sampling weights
++ optional strata / PSU / FPC). The pretest battery
+:func:`~diff_diff.did_had_pretest_workflow` adjudicates the design path
+and surfaces assumption violations.
 
 .. code-block:: python
 
@@ -420,8 +420,7 @@ Feature Comparison Table
    HeterogeneousAdoptionDiD (dCDH 2026) overlaps with the dedicated R
    package ``DIDHAD`` (de Chaisemartin et al., 2025), which covers the
    QUG case (Design 1'); diff-diff additionally covers Design 1 (no QUG,
-   ``WAS_{d_lower}``), the multi-period event-study extension (paper
-   Appendix B.2), and survey-design integration via Binder TSL.
+   ``WAS_{d_lower}``) and survey-design integration via Binder TSL.
 
 Migration Tips
 --------------
@@ -439,9 +438,8 @@ Migration Tips
 5. **Missing data**: diff-diff requires complete data; use ``balance_panel()``
    or ``dropna()`` first
 
-6. **Heterogeneous Adoption (HAD)**: If you need the broader HAD surface
-   beyond the QUG case that the R ``DIDHAD`` package covers - Design 1
-   (no QUG, ``WAS_{d_lower}``), the multi-period event-study extension, or
+6. **Heterogeneous Adoption (HAD)**: If you need surfaces the R ``DIDHAD``
+   package does not cover - Design 1 (no QUG, ``WAS_{d_lower}``) or
    survey-design integration - reach for
    :class:`~diff_diff.HeterogeneousAdoptionDiD`. See the
    `Heterogeneous Adoption (HAD)`_ section above for the migration pattern.

docs/troubleshooting.rst

@@ -483,28 +483,37 @@ HeterogeneousAdoptionDiD (HAD) Issues
 **Problem:** ``HeterogeneousAdoptionDiD`` resolves ``target_parameter`` to
 ``"WAS_d_lower"`` when you expected ``"WAS"`` (or vice versa).
 
-**Cause:** HAD auto-detects the design path from the dose distribution. Design
-1' (QUG case, ``d_lower = 0``) targets WAS by treating the smallest-dose
-units as a quasi-untreated anchor; Design 1 (no QUG, ``d_lower > 0``) targets
-``WAS_{d_lower}``. If your data has no observations at ``dose = 0`` the
-estimator routes to Design 1 even when you intend a WAS interpretation.
+**Cause:** HAD auto-detects the design path from the dose distribution. The
+``_detect_design`` rule resolves to Design 1' (``continuous_at_zero``,
+targets WAS) when EITHER ``d.min() == 0`` exactly OR ``d.min()`` is a small
+positive value below ``0.01 * median(|d|)`` (the small-share-of-treated
+escape clause). Otherwise (``d.min()`` larger than that threshold) the
+estimator routes to Design 1, with a further check for mass-point structure
+(modal fraction at ``d.min()`` exceeding 2% routes to ``mass_point``;
+otherwise ``continuous_near_d_lower``); both Design 1 paths target
+``WAS_{d_lower}``. So a Design 1 resolution only fires when ``d.min()``
+is meaningfully positive relative to the dose scale.
 
 **Solutions:**
 
 .. code-block:: python
 
    # Inspect the dose support before fitting
+   import numpy as np
+   d = data['dose'].to_numpy()
    print(data['dose'].describe())
-   print((data['dose'] == 0).sum(), "observations at dose=0")
+   print(f"d.min() = {d.min():.6g}; "
+         f"0.01 * median(|d|) = {0.01 * np.median(np.abs(d)):.6g}; "
+         f"d.min() < threshold => Design 1' (WAS)")
 
    # Check the resolved estimand after fitting
    results = est.fit(data, outcome_col='y', unit_col='unit',
                      time_col='period', dose_col='dose')
    print(f"Resolved: {results.target_parameter}")
 
-   # If you genuinely have a Design 1' panel but lack dose=0 rows, verify
-   # the dose variable encoding (e.g. log-transformed doses where 0 was
-   # mapped to a small positive value)
+   # If you intend Design 1' but `d.min()` exceeds the threshold, verify
+   # the dose-variable encoding (e.g. log-transformed doses where 0 was
+   # mapped to a small positive value larger than 1% of the median).
 
 "Mass-point fit fallback"
 ~~~~~~~~~~~~~~~~~~~~~~~~~