Address PR #366 CI review round 3 (1 P3): add duplicate-row gate to ContinuousDiD prerequisite summaries

Reviewer correctly noted that the round-2 wording lists
`has_never_treated` + `treatment_varies_within_unit == False` +
`is_balanced` as the "authoritative" ContinuousDiD pre-fit gates but
omits the duplicate-cell hard stop. Verified
`continuous_did.py:_precompute_structures` (line 818-823) builds
`outcome_matrix` cell-by-cell with last-row-wins on duplicate
`(unit, time)` keys - so absence of the `duplicate_unit_time_rows`
alert is also a real prerequisite, not just a style preference.

Updated wording in five places to add "+ absence of the
`duplicate_unit_time_rows` alert" alongside the other gates and
explain the silent-overwrite behavior:

- `diff_diff/profile.py` `TreatmentDoseShape` docstring
- `diff_diff/guides/llms-autonomous.txt` §2 field reference
- `diff_diff/guides/llms-autonomous.txt` §4.7 (continuous design feature)
- `diff_diff/guides/llms-autonomous.txt` §5.2 worked example reasoning
  chain (now lists four gates instead of three)
- `CHANGELOG.md` Unreleased entry
- `ROADMAP.md` AI-Agent Track building-block

Also softened "authoritative" -> "core field-based" since the
non-field-based duplicate-row gate makes the original phrasing
slightly misleading.

Added a test_guides.py regression asserting the autonomous guide
mentions `duplicate_unit_time_rows` so future wording changes can't
silently drop the gate from the summary.

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). 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.
+- **`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 core field-based 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`, plus the absence of the `duplicate_unit_time_rows` alert (the precompute path silently resolves duplicate `(unit, time)` cells via last-row-wins). 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"`.

ROADMAP.md

@@ -138,7 +138,7 @@ Long-running program, framed as "building toward" rather than with discrete ship
 - Baker et al. (2025) 8-step workflow enforcement in `diff_diff/practitioner.py`.
 - `practitioner_next_steps()` context-aware guidance.
 - Runtime LLM guides via `get_llm_guide(...)` (`llms.txt`, `llms-full.txt`, `llms-practitioner.txt`, `llms-autonomous.txt`), bundled in the wheel.
-- `profile_panel(df, ...)` returns a `PanelProfile` dataclass of structural facts about the panel - factual, not opinionated. Pairs with the `"autonomous"` guide variant (reference-shaped: estimator-support matrix + per-design-feature reasoning) so agents describe the data then consult a bundled reference rather than calling a deterministic recommender. `PanelProfile.outcome_shape` and `PanelProfile.treatment_dose` extensions add descriptive distributional context (count-likeness / bounded-support hints on numeric outcomes; dose support and zero-dose presence on continuous treatments). They are descriptive only — `outcome_shape.is_count_like` informs the WooldridgeDiD-QMLE-vs-linear-OLS judgment but does not gate it, and the authoritative ContinuousDiD pre-fit gates remain the existing `has_never_treated`, `treatment_varies_within_unit`, and `is_balanced` fields. The autonomous guide §5 walks through three end-to-end PanelProfile -> reasoning -> validation worked examples.
+- `profile_panel(df, ...)` returns a `PanelProfile` dataclass of structural facts about the panel - factual, not opinionated. Pairs with the `"autonomous"` guide variant (reference-shaped: estimator-support matrix + per-design-feature reasoning) so agents describe the data then consult a bundled reference rather than calling a deterministic recommender. `PanelProfile.outcome_shape` and `PanelProfile.treatment_dose` extensions add descriptive distributional context (count-likeness / bounded-support hints on numeric outcomes; dose support and zero-dose presence on continuous treatments). They are descriptive only — `outcome_shape.is_count_like` informs the WooldridgeDiD-QMLE-vs-linear-OLS judgment but does not gate it, and the core field-based ContinuousDiD pre-fit gates remain the existing `has_never_treated`, `treatment_varies_within_unit`, `is_balanced`, and the absence of the `duplicate_unit_time_rows` alert. The autonomous guide §5 walks through three end-to-end PanelProfile -> reasoning -> validation worked examples.
 - Package docstring leads with an "For AI agents" entry block so `help(diff_diff)` surfaces the agent entry points automatically.
 - Silent-operation warnings so agents and humans see the same signals at the same time.
 

diff_diff/guides/llms-autonomous.txt

@@ -198,12 +198,15 @@ view. Every field below appears as a top-level key in that dict.
 - **`treatment_dose: Optional[TreatmentDoseShape]`** - distributional
   facts for continuous-treatment dose columns; `None` unless
   `treatment_type == "continuous"`. **Descriptive only — none of these
-  sub-fields are `ContinuousDiD` prerequisites.** The authoritative
+  sub-fields are `ContinuousDiD` prerequisites.** The core field-based
   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:
+  rejection, plus the absence of the `duplicate_unit_time_rows` alert
+  (the precompute path silently resolves duplicate `(unit, time)`
+  cells via last-row-wins, so duplicates must be removed before
+  fitting). Sub-fields:
     - `n_distinct_doses: int` - count of distinct non-NaN dose values
       (including zero if observed). Useful supplement to the gate
       checks for understanding the dose support.
@@ -496,11 +499,13 @@ When `treatment_type == "continuous"`:
   scalar first-stage adoption summary. Useful when adoption is
   graded rather than binary.
 
-The authoritative ContinuousDiD pre-fit gates are
-`has_never_treated == True` (unit-level never-treated control) and
+The core field-based ContinuousDiD pre-fit gates are
+`has_never_treated == True` (unit-level never-treated control),
 `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`,
+constancy, including pre-treatment zeros), `is_balanced == True`, and
+the absence of the `duplicate_unit_time_rows` alert (the precompute
+path silently resolves duplicate cells via last-row-wins). 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
@@ -729,19 +734,21 @@ 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 are checked against the authoritative
-   gates (the existing top-level `PanelProfile` fields, not
-   `treatment_dose`): `has_never_treated == True` (unit-level
+2. ContinuousDiD prerequisites are checked against the core
+   field-based 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.
+   check), `is_balanced == True`, and the absence of a
+   `duplicate_unit_time_rows` alert (the precompute path silently
+   resolves duplicate cells via last-row-wins, so duplicates must
+   be removed before fitting). All four 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

diff_diff/profile.py

@@ -67,12 +67,15 @@ class TreatmentDoseShape:
 
     Populated on :class:`PanelProfile` only when ``treatment_type ==
     "continuous"``; ``None`` otherwise. **Descriptive only** — none of
-    these fields are ``ContinuousDiD`` prerequisites. The authoritative
-    gates are ``PanelProfile.has_never_treated`` (unit-level
+    these fields are ``ContinuousDiD`` prerequisites. The core
+    field-based gates are ``PanelProfile.has_never_treated`` (unit-level
     never-treated existence), ``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``.
+    rejection), and ``PanelProfile.is_balanced``, plus the absence of
+    the ``duplicate_unit_time_rows`` alert (``ContinuousDiD``'s
+    precompute path silently resolves duplicate ``(unit, time)`` cells
+    via last-row-wins, so duplicates must be removed before fitting).
 
     ``has_zero_dose`` is a row-level fact ("at least one observation has
     dose == 0"); it is NOT a substitute for ``has_never_treated``, which

tests/test_guides.py

@@ -45,6 +45,18 @@ def test_content_stability_autonomous_fingerprints():
     # has_never_treated is the authoritative ContinuousDiD gate;
     # treatment_dose fields are descriptive only.
     assert "has_never_treated" in text
+    # The ContinuousDiD prerequisite summary must continue to mention
+    # the duplicate-row hard stop alongside the field-based gates -
+    # `_precompute_structures()` silently resolves duplicate cells via
+    # last-row-wins, so a reader treating the summary as exhaustive
+    # could route duplicate-containing panels into a silent-overwrite
+    # path. Guard against that wording regression.
+    assert "duplicate_unit_time_rows" in text, (
+        "ContinuousDiD prerequisite summary must mention the "
+        "`duplicate_unit_time_rows` alert: the precompute path resolves "
+        "duplicate (unit, time) cells via last-row-wins, so duplicates "
+        "must be removed before fitting."
+    )
 
 
 def test_autonomous_contains_worked_examples_section():