Address PR #366 CI review round 1: scope TreatmentDoseShape as descriptive-only; fix WooldridgeDiD method kwarg

P1 (TreatmentDoseShape vs ContinuousDiD contract):
- Reviewer correctly flagged that the new `is_time_invariant` field
  (per-unit non-zero distinct-count) does NOT match the actual
  `ContinuousDiD.fit()` gate at `continuous_did.py:222-228`, which
  uses `df.groupby(unit)[dose].nunique() > 1` over the FULL dose
  column (including pre-treatment zeros). My nonzero-only check
  silently classified `0,0,d,d` paths as time-invariant while
  ContinuousDiD would reject them.
- Removed `is_time_invariant` field from `TreatmentDoseShape`
  entirely. The pre-existing `PanelProfile.treatment_varies_within_unit`
  field already encodes the correct ContinuousDiD prerequisite (matches
  the estimator's nunique check at line 224) and is correctly documented
  in §2 of the autonomous guide. Adding a second, narrower, mismatched
  gate was confusing - the reviewer's "scope as descriptive-only" path
  is the cleaner fix.
- Reframed `TreatmentDoseShape` docstring + autonomous guide §2
  field reference: explicitly NOT a ContinuousDiD prerequisite.
  `n_distinct_doses`, `has_zero_dose`, `dose_min/max/mean` provide
  descriptive distributional context; `has_never_treated` (unit-level)
  + `treatment_varies_within_unit == False` (full-path constancy) +
  `is_balanced` are the authoritative gates.
- Rewrote §5.2 worked example reasoning chain to use the existing
  correct gates and added a counter-example showing
  `has_zero_dose=True` does NOT imply `has_never_treated=True` (the
  row-level vs unit-level distinction).
- Added `test_treatment_dose_does_not_gate_continuous_did` covering
  the two contradictory cases the reviewer named: (1) `0,0,d,d`
  within-unit dose path, asserting `treatment_varies_within_unit=True`
  (the actual ContinuousDiD gate fires correctly); (2) row-level zeros
  without never-treated units, asserting `has_zero_dose=True` BUT
  `has_never_treated=False` (the two facts are distinct).
- Removed `test_treatment_dose_continuous_time_varying_within_unit`
  and `test_treatment_dose_distinguishes_doses_at_high_precision` -
  both tested the dropped `is_time_invariant` field.

P2 (WooldridgeDiD constructor kwarg):
- The autonomous guide §5.3 worked example used
  `WooldridgeDiD(family="poisson")` but the actual constructor at
  `wooldridge.py:264` takes `method=`. Following the example would
  raise `TypeError: __init__() got an unexpected keyword argument
  'family'`. Fixed in two places (the prose and the code snippet)
  and added a negative assertion in `test_guides.py` to prevent
  regression: `assert 'WooldridgeDiD(family="poisson")' not in text`.

CHANGELOG updated to reflect the revised TreatmentDoseShape scope.

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

Author: igerber

CHANGELOG.md

@@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-- **`PanelProfile.outcome_shape` and `PanelProfile.treatment_dose` extensions + `llms-autonomous.txt` worked examples (Wave 2 of the AI-agent enablement track).** `profile_panel(...)` now populates two new optional sub-dataclasses on the returned `PanelProfile`: `outcome_shape: Optional[OutcomeShape]` (numeric outcomes only — exposes `n_distinct_values`, `pct_zeros`, `value_min` / `value_max`, `skewness` and `excess_kurtosis` (NaN-safe; `None` when `n_distinct_values < 3` or variance is zero), `is_integer_valued`, `is_count_like` (heuristic: integer-valued AND has zeros AND right-skewed AND > 2 distinct values; flags WooldridgeDiD QMLE consideration over linear OLS), `is_bounded_unit` ([0, 1] support)) and `treatment_dose: Optional[TreatmentDoseShape]` (continuous treatments only — exposes `n_distinct_doses`, `has_zero_dose`, `dose_min` / `dose_max` / `dose_mean` over non-zero doses, `is_time_invariant` (per-unit non-zero doses have at most one distinct value; gates the ContinuousDiD `fit()`-time prerequisites pre-fit)). Both fields are `None` when their classification gate is not met (e.g., `treatment_dose is None` for binary treatments). `to_dict()` serializes the nested dataclasses as JSON-compatible nested dicts. New exports: `OutcomeShape`, `TreatmentDoseShape` from top-level `diff_diff`. `llms-autonomous.txt` gains a new §5 "Worked examples" section with three end-to-end PanelProfile -> reasoning -> validation walkthroughs (binary staggered with never-treated controls, continuous dose with zero baseline, count-shaped outcome) plus §2 field-reference subsections for the new shape fields and §4.7 / §4.11 cross-references for outcome-shape considerations. Existing §5-§8 of the autonomous guide are renumbered to §6-§9. Descriptive only — no recommender language inside the worked examples.
+- **`PanelProfile.outcome_shape` and `PanelProfile.treatment_dose` extensions + `llms-autonomous.txt` worked examples (Wave 2 of the AI-agent enablement track).** `profile_panel(...)` now populates two new optional sub-dataclasses on the returned `PanelProfile`: `outcome_shape: Optional[OutcomeShape]` (numeric outcomes only — exposes `n_distinct_values`, `pct_zeros`, `value_min` / `value_max`, `skewness` and `excess_kurtosis` (NaN-safe; `None` when `n_distinct_values < 3` or variance is zero), `is_integer_valued`, `is_count_like` (heuristic: integer-valued AND has zeros AND right-skewed AND > 2 distinct values; flags WooldridgeDiD QMLE consideration over linear OLS), `is_bounded_unit` ([0, 1] support)) and `treatment_dose: Optional[TreatmentDoseShape]` (continuous treatments only — exposes `n_distinct_doses`, `has_zero_dose`, `dose_min` / `dose_max` / `dose_mean` over non-zero doses). Both `OutcomeShape` and `TreatmentDoseShape` are descriptive only; the authoritative pre-fit gates for `ContinuousDiD` remain the existing `PanelProfile.has_never_treated` (unit-level), `PanelProfile.treatment_varies_within_unit == False` (per-unit full-path dose constancy, matching `ContinuousDiD.fit()`'s `df.groupby(unit)[dose].nunique() > 1` rejection), and `PanelProfile.is_balanced`. The shape extensions provide distributional context (effect-size range, count-shape detection) that supplements but does not replace those gates. Both fields are `None` when their classification gate is not met (e.g., `treatment_dose is None` for binary treatments). `to_dict()` serializes the nested dataclasses as JSON-compatible nested dicts. New exports: `OutcomeShape`, `TreatmentDoseShape` from top-level `diff_diff`. `llms-autonomous.txt` gains a new §5 "Worked examples" section with three end-to-end PanelProfile -> reasoning -> validation walkthroughs (binary staggered with never-treated controls, continuous dose with zero baseline, count-shaped outcome) plus §2 field-reference subsections for the new shape fields and §4.7 / §4.11 cross-references for outcome-shape considerations. Existing §5-§8 of the autonomous guide are renumbered to §6-§9. Descriptive only — no recommender language inside the worked examples.
 - **`HeterogeneousAdoptionDiD.fit(survey=..., weights=...)` on continuous-dose paths (Phase 4.5 survey support).** The `continuous_at_zero` (paper Design 1') and `continuous_near_d_lower` (Design 1 continuous-near-d̲) designs accept survey weights through two interchangeable kwargs: `weights=<array>` (pweight shortcut, weighted-robust SE from the CCT-2014 lprobust port) and `survey=SurveyDesign(weights, strata, psu, fpc)` (design-based inference via Binder-TSL variance using the existing `compute_survey_if_variance` helper at `diff_diff/survey.py:1802`). Point estimates match across both entry paths; SE diverges by design (pweight-only vs PSU-aggregated). `HeterogeneousAdoptionDiDResults.survey_metadata` is a repo-standard `SurveyMetadata` dataclass (weight_type / effective_n / design_effect / sum_weights / weight_range / n_strata / n_psu / df_survey); HAD-specific extras (`variance_formula` label, `effective_dose_mean`) are separate top-level result fields. `to_dict()` surfaces the full `SurveyMetadata` object plus `variance_formula` + `effective_dose_mean`; `summary()` renders `variance_formula`, `effective_n`, `effective_dose_mean`, and (when the survey= path is used) `df_survey`; `__repr__` surfaces `variance_formula` + `effective_dose_mean` when present. The HAD `mass_point` design and `aggregate="event_study"` path raise `NotImplementedError` under survey/weights (deferred to Phase 4.5 B: weighted 2SLS + event-study survey composition); the HAD pretests stay unweighted in this release (Phase 4.5 C). Parity ceiling acknowledged — no public weighted-CCF bias-corrected local-linear reference exists in any language; methodology confidence comes from (1) uniform-weights bit-parity at `atol=1e-14` on the full lprobust output struct, (2) cross-language weighted-OLS parity (manual R reference) at `atol=1e-12`, and (3) Monte Carlo oracle consistency on known-τ DGPs. `_nprobust_port.lprobust` gains `weights=` and `return_influence=` (used internally by the Binder-TSL path); `bias_corrected_local_linear` removes the Phase 1c `NotImplementedError` on `weights=` and forwards. Auto-bandwidth selection remains unweighted in this release — pass `h`/`b` explicitly for weight-aware bandwidths. See `docs/methodology/REGISTRY.md` §HeterogeneousAdoptionDiD "Weighted extension (Phase 4.5 survey support)".
 - **`stute_joint_pretest`, `joint_pretrends_test`, `joint_homogeneity_test` + `StuteJointResult`** (HeterogeneousAdoptionDiD Phase 3 follow-up). Joint Cramér-von Mises pretests across K horizons with shared-η Mammen wild bootstrap (preserves vector-valued empirical-process unit-level dependence per Delgado-Manteiga 2001 / Hlávka-Hušková 2020). The core `stute_joint_pretest` is residuals-in; two thin data-in wrappers construct per-horizon residuals for the two nulls the paper spells out: mean-independence (step 2 pre-trends, `OLS(Y_t − Y_base ~ 1)` per pre-period) and linearity (step 3 joint, `OLS(Y_t − Y_base ~ 1 + D)` per post-period). Sum-of-CvMs aggregation (`S_joint = Σ_k S_k`); per-horizon scale-invariant exact-linear short-circuit. Closes the paper Section 4.2 step-2 gap that Phase 3 `did_had_pretest_workflow` previously flagged with an "Assumption 7 pre-trends test NOT run" caveat. See `docs/methodology/REGISTRY.md` §HeterogeneousAdoptionDiD "Joint Stute tests" for algorithm, invariants, and scope exclusion of Eq 18 linear-trend detrending (deferred to Phase 4 Pierce-Schott replication).
 - **`did_had_pretest_workflow(aggregate="event_study")`**: multi-period dispatch on balanced ≥3-period panels. Runs QUG at `F` + joint pre-trends Stute across earlier pre-periods + joint homogeneity-linearity Stute across post-periods. Step 2 closure requires ≥2 pre-periods; with only a single pre-period (the base `F-1`) `pretrends_joint=None` and the verdict flags the skip. Reuses the Phase 2b event-study panel validator (last-cohort auto-filter under staggered timing with `UserWarning`; `ValueError` when `first_treat_col=None` and the panel is staggered). The data-in wrappers `joint_pretrends_test` and `joint_homogeneity_test` also route through that same validator internally, so direct wrapper calls inherit the last-cohort filter and constant-post-dose invariant. `HADPretestReport` extended with `pretrends_joint`, `homogeneity_joint`, and `aggregate` fields; serialization methods (`summary`, `to_dict`, `to_dataframe`, `__repr__`) preserve the Phase 3 output bit-exactly on `aggregate="overall"` — no `aggregate` key, no header row, no schema drift — and only surface the new fields on `aggregate="event_study"`.

diff_diff/guides/llms-autonomous.txt

@@ -197,18 +197,27 @@ view. Every field below appears as a top-level key in that dict.
       model can predict outside `[0, 1]`).
 - **`treatment_dose: Optional[TreatmentDoseShape]`** - distributional
   facts for continuous-treatment dose columns; `None` unless
-  `treatment_type == "continuous"`. Sub-fields:
+  `treatment_type == "continuous"`. **Descriptive only — none of these
+  sub-fields are `ContinuousDiD` prerequisites.** The authoritative
+  pre-fit gates are `has_never_treated` (unit-level, above) for the
+  zero-dose-control requirement and `treatment_varies_within_unit ==
+  False` (above) for per-unit full-path dose constancy, matching
+  `ContinuousDiD.fit()`'s `df.groupby(unit)[dose].nunique() > 1`
+  rejection. Sub-fields:
     - `n_distinct_doses: int` - count of distinct non-NaN dose values
-      (including zero if observed).
+      (including zero if observed). Useful supplement to the gate
+      checks for understanding the dose support.
     - `has_zero_dose: bool` - at least one unit-period has dose
-      exactly zero. Required by `ContinuousDiD` (`P(D=0) > 0`); when
-      `False` the estimator cannot identify the dose-response curve.
-    - `dose_min: float`, `dose_max: float`, `dose_mean: float` - over
-      the strictly non-zero doses (NaN if no non-zero values exist).
-    - `is_time_invariant: bool` - within every unit, the set of
-      distinct non-zero dose values has size at most one (always-zero
-      units are skipped). Required by `ContinuousDiD`; when `False`,
-      `fit()` will raise. See §5.2 for a worked example.
+      exactly zero. **Row-level fact**: a panel can have
+      `has_zero_dose == True` (some pre-treatment rows are zero) while
+      `has_never_treated == False` (every unit eventually treated), in
+      which case the panel still fails the ContinuousDiD never-treated
+      gate. Consult `has_never_treated` for the unit-level gate.
+    - `dose_min: float`, `dose_max: float`, `dose_mean: float` -
+      computed over the strictly non-zero doses; useful for effect-size
+      context and dose-response interpretation. See §5.2 for a worked
+      example showing how these fields supplement (not replace) the
+      authoritative gates.
 
 ### Alerts
 
@@ -334,8 +343,10 @@ estimator from the remaining rows (CS/SA/dCDH/Imputation/TwoStage/
 Stacked/ETWFE all accept unbalanced input, with some caveats in
 their own docs).
 
-For two common prerequisite-resolution patterns walked through end-to-end
-(continuous dose with `treatment_dose` introspection, and count-shaped
+For two common reasoning patterns walked through end-to-end (continuous
+dose checked against the existing `has_never_treated` /
+`treatment_varies_within_unit` / `is_balanced` gates with
+`treatment_dose` providing descriptive context, and count-shaped
 outcome with `outcome_shape` introspection), see §5.2 and §5.3.
 
 
@@ -485,10 +496,15 @@ When `treatment_type == "continuous"`:
   scalar first-stage adoption summary. Useful when adoption is
   graded rather than binary.
 
-The new `PanelProfile.treatment_dose` sub-fields (`has_zero_dose`,
-`is_time_invariant`, `n_distinct_doses`) let you check the three
-ContinuousDiD prerequisites pre-fit; §5.2 walks through the full
-profile -> reasoning -> validation flow.
+The authoritative ContinuousDiD pre-fit gates are
+`has_never_treated == True` (unit-level never-treated control) and
+`treatment_varies_within_unit == False` (per-unit full-path dose
+constancy, including pre-treatment zeros) plus `is_balanced == True`.
+The `PanelProfile.treatment_dose` sub-fields (`n_distinct_doses`,
+`dose_min/max/mean`, `has_zero_dose`) provide descriptive context
+about the dose support, but are NOT themselves prerequisite gates;
+§5.2 walks through the full profile -> reasoning -> validation flow
+including the gate check.
 
 ### §4.8 Few treated units (one or a handful)
 
@@ -700,7 +716,6 @@ PanelProfile(
         n_distinct_doses=4,
         has_zero_dose=True,
         dose_min=1.0, dose_max=4.0, dose_mean=2.4,
-        is_time_invariant=True,
     ),
     outcome_shape=OutcomeShape(
         is_count_like=False, is_bounded_unit=False, ...
@@ -714,18 +729,33 @@ Reasoning chain:
 1. `treatment_type == "continuous"` -> §3 row narrows to
    `ContinuousDiD` (`✓`) and `HeterogeneousAdoptionDiD` (`partial`,
    for graded adoption). All other estimators are `✗` on continuous.
-2. ContinuousDiD prerequisites map directly onto the new dose fields:
-   `treatment_dose.has_zero_dose == True` (P(D=0) > 0 satisfied),
-   `treatment_dose.is_time_invariant == True` (per-unit constant
-   dose), `is_balanced == True`. All three pass, so `ContinuousDiD`
-   is in scope. (If any failed, `fit()` would raise `ValueError`.)
-3. Counter-example: had `is_time_invariant == False` (a unit's
-   nonzero dose changed across periods), `ContinuousDiD` would not
-   apply. The two paths from there are (a)
-   `HeterogeneousAdoptionDiD` if a scalar adoption summary fits, or
-   (b) aggregate the dose to a binary indicator and fall back to a
-   binary staggered estimator.
-4. Fit `ContinuousDiD`; the result object exposes the dose-response
+2. ContinuousDiD prerequisites are checked against the authoritative
+   gates (the existing top-level `PanelProfile` fields, not
+   `treatment_dose`): `has_never_treated == True` (unit-level
+   never-treated control, mapping to `first_treat == 0` units in
+   `ContinuousDiD.fit()`), `treatment_varies_within_unit == False`
+   (per-unit full-path dose constancy, matching
+   `ContinuousDiD.fit()`'s `df.groupby(unit)[dose].nunique() > 1`
+   check), and `is_balanced == True`. All three pass, so
+   `ContinuousDiD` is in scope. The `treatment_dose` sub-fields
+   (`n_distinct_doses`, `has_zero_dose`, `dose_min/max/mean`)
+   provide descriptive context — useful for reasoning about dose
+   support and the eventual dose-response interpretation, but not
+   themselves gates.
+3. Counter-example: had `treatment_varies_within_unit == True` (any
+   unit's full dose path - including pre-treatment zeros - has more
+   than one distinct value, e.g., a `0,0,d,d` adoption path with
+   varying nonzero `d`), `ContinuousDiD` would not apply. The two
+   paths from there are (a) `HeterogeneousAdoptionDiD` if a scalar
+   adoption summary fits, or (b) aggregate the dose to a binary
+   indicator and fall back to a binary staggered estimator.
+4. Counter-example: had `has_never_treated == False` (every unit
+   eventually treated, even if pre-treatment rows have zero dose so
+   `treatment_dose.has_zero_dose == True`), `ContinuousDiD` would
+   reject the panel under default `control_group="never_treated"`.
+   Row-level zeros are not a substitute for unit-level
+   never-treated controls.
+5. Fit `ContinuousDiD`; the result object exposes the dose-response
    curve (`ATT(d)`) and average causal response (`ACRT(d)`); choose
    the headline estimand based on the business question (overall
    ATT under PT, or the dose-response curve under Strong PT).
@@ -765,10 +795,10 @@ Reasoning chain:
    raw count gives unbiased point estimates of the additive effect
    but its asymptotic SEs assume normal-shaped errors, which a
    right-skewed count distribution violates. `WooldridgeDiD`
-   (`family="poisson"`) estimates the multiplicative
+   (`method="poisson"`) estimates the multiplicative
    (log-link) effect under QMLE with correct asymptotic SEs, and
    maps onto the staggered design natively.
-3. Decision: fit `WooldridgeDiD(family="poisson")` for the
+3. Decision: fit `WooldridgeDiD(method="poisson")` for the
    primary estimate; report the multiplicative effect (proportional
    change) rather than the additive effect. Optionally fit a linear
    DiD as a robustness check and document which scale the headline