Address PR #366 CI review round 17 (1 P1): split "no never-treated" vs "negative dose" branches; HAD only valid on the former

igerber · claude · igerber · commit 872abc8bc04f · 2026-04-25T08:39:56.000-04:00
Reviewer correctly noted that the round-15/16 wording listed `HeterogeneousAdoptionDiD` as a routing alternative whenever `ContinuousDiD` fails on the dose-related preflights, but HAD itself requires non-negative dose support and raises on negative post-period dose at `had.py:1450-1459` (paper Section 2). On a panel with `dose_min < 0`, routing to HAD silently steers an agent into the same fit-time error. Verified the rejection at `had.py:1450-1459`. Reworded every site to split the two failure modes: - Branch (a): `has_never_treated == False` (no zero-dose controls but all observed doses non-negative). `ContinuousDiD` does not apply (Remark 3.1 not implemented). HAD IS a routing alternative on this branch (HAD's contract requires non-negative dose, satisfied here); linear DiD with a continuous covariate is another. - Branch (e): `dose_min < 0` (negative treated doses). `ContinuousDiD` does not apply AND HAD is **not** a fallback either — HAD raises on negative post-period dose (`had.py:1450-1459`). Linear DiD with a signed continuous covariate is the applicable alternative on this branch. Updated wording across: - `diff_diff/profile.py` `TreatmentDoseShape` docstring (refactored from item-by-item duplication into a numbered list with a single "Routing alternatives when (1) or (5) fails" section that splits the two branches; trimmed redundancy). - `diff_diff/guides/llms-autonomous.txt` §2 field reference (split the When-(1)-or-(5)-fails paragraph into the two branches). - `diff_diff/guides/llms-autonomous.txt` §4.7 trailing paragraph (consolidated to a pointer at §2's split discussion). - `diff_diff/guides/llms-autonomous.txt` §5.2 reasoning chain counter-example #4 (no never-treated branch: HAD applies) and counter-example #5 (negative-dose branch: HAD does NOT apply, cite `had.py:1450-1459`). - `CHANGELOG.md` Wave 2 entry. - `ROADMAP.md` AI-Agent Track building block. - `tests/test_profile_panel.py` two test docstrings/comments. Added `test_autonomous_negative_dose_path_does_not_route_to_had` in `tests/test_guides.py` asserting that §5.2 explicitly cites `had.py:1450-1459` on the negative-dose branch (used a single- line fingerprint since the prose phrase "non-negative dose support" is split across newlines in the rendered guide). Length housekeeping: trimmed counter-example #4 and #5 prose + §4.7 trailing paragraph to point at §2's split discussion; autonomous (65374 chars) < full (66031), `test_full_is_largest` green. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/ROADMAP.md b/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). Most fields are descriptive context. `outcome_shape.is_count_like` informs the WooldridgeDiD-QMLE-vs-linear-OLS judgment but does not gate it. `profile_panel` does not see the separate `first_treat` column that `ContinuousDiD.fit()` consumes; under the canonical `ContinuousDiD` setup (per-unit time-invariant dose `D_i` + separate `first_treat`), several preflight checks become predictive on the dose column: `has_never_treated` (proxies `P(D=0) > 0`), `treatment_varies_within_unit == False` (actual fit-time gate), `is_balanced` (actual fit-time gate), absence of the `duplicate_unit_time_rows` alert (silent last-row-wins overwrite path), and `treatment_dose.dose_min > 0` (predicts strictly-positive-treated-dose). When `has_never_treated` or `dose_min > 0` fails, `ContinuousDiD` as currently implemented does not apply (Remark 3.1 lowest-dose-as-control is not implemented). Routing alternatives include `HeterogeneousAdoptionDiD` and linear DiD with a continuous covariate; re-encoding the treatment column is an agent-side preprocessing choice that is not documented in REGISTRY as a supported fallback. The estimator's force-zero coercion on inconsistent `first_treat == 0 + nonzero dose` inputs is implementation behavior, not a documented method for manufacturing controls. 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). Most fields are descriptive context. `outcome_shape.is_count_like` informs the WooldridgeDiD-QMLE-vs-linear-OLS judgment but does not gate it. `profile_panel` does not see the separate `first_treat` column that `ContinuousDiD.fit()` consumes; under the canonical `ContinuousDiD` setup (per-unit time-invariant dose `D_i` + separate `first_treat`), several preflight checks become predictive on the dose column: `has_never_treated` (proxies `P(D=0) > 0`), `treatment_varies_within_unit == False` (actual fit-time gate), `is_balanced` (actual fit-time gate), absence of the `duplicate_unit_time_rows` alert (silent last-row-wins overwrite path), and `treatment_dose.dose_min > 0` (predicts strictly-positive-treated-dose). When `has_never_treated == False` but all doses are non-negative, `ContinuousDiD` does not apply (Remark 3.1 not implemented); `HeterogeneousAdoptionDiD` is a routing alternative on this branch. When `dose_min <= 0` (negative doses), neither `ContinuousDiD` nor `HeterogeneousAdoptionDiD` apply (HAD raises on negative post-period dose); linear DiD with a signed continuous covariate is the applicable alternative. Re-encoding the treatment column is an agent-side preprocessing choice that is not documented in REGISTRY as a supported fallback. The estimator's force-zero coercion on inconsistent `first_treat == 0 + nonzero dose` inputs is implementation behavior, not a documented method for manufacturing controls. 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 --git a/diff_diff/guides/llms-autonomous.txt b/diff_diff/guides/llms-autonomous.txt
@@ -241,20 +241,30 @@ view. Every field below appears as a top-level key in that dict.
   treated units carry their constant dose across all periods so
   `dose_min` over non-zero values is the smallest treated dose).
 
-  When `has_never_treated == False` or `dose_min <= 0`,
-  `ContinuousDiD` as currently implemented does not apply (Remark
-  3.1 lowest-dose-as-control is not implemented). Routing
-  alternatives that do not require `P(D=0) > 0`:
-  `HeterogeneousAdoptionDiD` for graded-adoption designs, or
-  linear DiD with the treatment as a continuous covariate.
-  Re-encoding the treatment column (shifting, absolute value,
-  etc.) is an agent-side preprocessing choice that changes the
+  When `has_never_treated == False` (no zero-dose controls but
+  all observed doses non-negative), `ContinuousDiD` as currently
+  implemented does not apply (Remark 3.1 lowest-dose-as-control
+  is not implemented). Routing alternatives that do not require
+  `P(D=0) > 0`: `HeterogeneousAdoptionDiD` for graded-adoption
+  designs (HAD's own contract requires non-negative dose, which
+  this branch satisfies), or linear DiD with the treatment as a
+  continuous covariate. When `dose_min <= 0` (negative treated
+  doses), the situation is different: `ContinuousDiD` does not
+  apply, and `HeterogeneousAdoptionDiD` is **not** a fallback
+  either — HAD raises on negative post-period dose
+  (`had.py:1450-1459`). The applicable routing alternative on
+  the negative-dose branch is linear DiD with the treatment as
+  a signed continuous covariate. Re-encoding the treatment
+  column to a non-negative scale (shifting, absolute value, etc.)
+  is an agent-side preprocessing choice that changes the
   estimand and is not documented in REGISTRY as a supported
-  fallback. Do not relabel positive- or negative-dose units as
-  `first_treat == 0`: that triggers the force-zero coercion
-  path, which is implementation behavior for inconsistent inputs
-  (e.g., an accidentally-nonzero row on a never-treated unit),
-  not a documented routing option.
+  fallback; if the agent does re-encode, both `ContinuousDiD`
+  and `HeterogeneousAdoptionDiD` become candidates again on the
+  re-encoded scale. Do not relabel positive- or negative-dose
+  units as `first_treat == 0`: that triggers the force-zero
+  coercion path, which is implementation behavior for
+  inconsistent inputs (e.g., an accidentally-nonzero row on a
+  never-treated unit), not a documented routing option.
 
   The agent must still validate the supplied `first_treat` column
   independently: it must contain at least one `first_treat == 0`
@@ -563,18 +573,10 @@ When `treatment_type == "continuous"`:
   overwritten with last-row-wins (a hard preflight veto, not a
   fit-time raise — the agent must deduplicate before fitting); (a)
   and (e) hold under the canonical setup. When (a) or (e) fails,
-  `ContinuousDiD` as currently implemented does not apply (Remark
-  3.1 lowest-dose-as-control is not implemented). Routing
-  alternatives that do not require `P(D=0) > 0` are
-  `HeterogeneousAdoptionDiD` (graded adoption) and linear DiD with
-  a continuous covariate. Re-encoding the treatment column is an
-  agent-side preprocessing choice that changes the estimand and is
-  not documented in REGISTRY as a supported fallback. Do not
-  relabel positive-dose or negative-dose units as
-  `first_treat == 0` to manufacture controls: that triggers
-  `ContinuousDiD.fit()`'s force-zero coercion path
-  (`UserWarning`), which is implementation behavior for
-  inconsistent inputs, not a documented methodological option.
+  see §2 for the full routing-alternatives discussion (the two
+  branches differ: HAD applies on the no-never-treated branch but
+  not on the negative-dose branch, since HAD requires non-negative
+  dose support per `had.py:1450-1459`).
   Note that staggered adoption IS supported natively (adoption
   timing is expressed via the `first_treat` column, not via
   within-unit dose variation), and `ContinuousDiD.fit()` applies
@@ -886,39 +888,27 @@ Reasoning chain:
    indicator and fall back to a binary staggered estimator.
 4. Counter-example: had `has_never_treated == False` (every unit
    eventually treated, even if some pre-treatment rows have zero
-   dose so `treatment_dose.has_zero_dose == True`), the dose
-   column would carry no never-treated unit. With a `first_treat`
-   column consistent with the dose column on per-unit
-   treated/untreated status, `ContinuousDiD.fit()` would reject
-   the panel under both `control_group="never_treated"` and
+   dose so `treatment_dose.has_zero_dose == True`),
+   `ContinuousDiD.fit()` would reject the panel under both
+   `control_group="never_treated"` and
    `control_group="not_yet_treated"` because Remark 3.1
-   lowest-dose-as-control is not yet implemented. `ContinuousDiD`
-   as currently implemented does not apply on this panel.
-   Available routing alternatives that do not require
-   `P(D=0) > 0`: linear DiD with the treatment as a continuous
-   covariate, or `HeterogeneousAdoptionDiD` for graded-adoption
-   designs. Re-encoding the treatment to a scale that contains a
-   true never-treated group is an agent-side preprocessing choice
-   that changes the estimand; it is not documented in REGISTRY as
-   a supported fallback. Do not relabel not-yet-treated units as
-   `first_treat == 0` to manufacture controls; the force-zero
-   coercion path is implementation behavior for inconsistent
-   inputs, not a documented method for manufacturing
-   never-treated controls.
+   lowest-dose-as-control is not yet implemented. On this branch
+   (no never-treated controls but doses still non-negative),
+   `HeterogeneousAdoptionDiD` IS a routing alternative for
+   graded-adoption designs, and linear DiD with the treatment as
+   a continuous covariate is another; see §2 for the full routing
+   discussion.
 5. Counter-example: had `treatment_dose.dose_min < 0` (continuous
    panel with some negative-valued treated doses, e.g. a
    centered-around-zero treatment encoding), with a `first_treat`
-   column consistent with the dose column (negative-dose units
-   labeled `first_treat > 0`), `ContinuousDiD.fit()` would raise
-   at line 287-294 ("Dose must be strictly positive for treated
-   units (D > 0)"). The principled fixes are to re-encode the
-   treatment to a non-negative support (e.g. shift or absolute
-   value, with the methodology change documented and the new
-   estimand reported on the re-encoded scale) or to route to a
-   different estimator. Do not relabel negative-dose units as
-   `first_treat == 0` to coerce them away — that is implementation
-   behavior for inconsistent inputs, not a documented routing
-   option.
+   column consistent with the dose column, `ContinuousDiD.fit()`
+   would raise at line 287-294 ("Dose must be strictly positive
+   for treated units"). `HeterogeneousAdoptionDiD` is **not** a
+   routing alternative here either — HAD requires non-negative
+   dose support (`had.py:1450-1459`, paper Section 2). The
+   applicable alternative is linear DiD with the treatment as a
+   signed continuous covariate; see §2 for the full routing
+   discussion.
 6. 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
diff --git a/diff_diff/profile.py b/diff_diff/profile.py
@@ -87,19 +87,7 @@ class TreatmentDoseShape:
        lowest-dose-as-control not yet implemented), because the
        canonical setup ties ``first_treat == 0`` to ``D_i == 0``.
        Failure means no never-treated controls exist on the dose
-       column. ``ContinuousDiD`` as currently implemented does not
-       apply (the paper's lowest-dose-as-control fallback in Remark
-       3.1 is not implemented here). Routing alternatives that do
-       not require ``P(D=0) > 0``: ``HeterogeneousAdoptionDiD`` for
-       graded-adoption designs, or linear DiD with the treatment
-       as a continuous covariate. Re-encoding the treatment column
-       to a different scale is an agent-side preprocessing choice
-       that changes the estimand; it is **not** documented in
-       REGISTRY as a supported fallback. Do **not** relabel
-       positive-dose units as ``first_treat == 0`` either: that
-       triggers ``fit()``'s force-zero coercion path, which is
-       implementation behavior for inconsistent inputs and is also
-       not a documented routing option.
+       column; see routing notes below.
     2. ``PanelProfile.treatment_varies_within_unit == False``
        (per-unit full-path dose constancy on the dose column). This
        IS the actual fit-time gate, matching
@@ -120,20 +108,34 @@ class TreatmentDoseShape:
        Predicts ``ContinuousDiD.fit()``'s strictly-positive-treated-
        dose requirement (raises ``ValueError`` on negative dose for
        ``first_treat > 0`` units, ``continuous_did.py:287-294``).
-       Under the canonical setup, treated units carry their dose
-       across all periods so ``dose_min`` over non-zero values
-       reflects the smallest treated dose. Failure means some
-       treated units have negative dose; ``ContinuousDiD`` as
-       currently implemented does not apply. Routing alternatives:
-       ``HeterogeneousAdoptionDiD`` or linear DiD with the
-       treatment as a continuous covariate. Re-encoding the
-       treatment to a non-negative scale is an agent-side
-       preprocessing choice that changes the estimand; not
-       documented in REGISTRY as a supported fallback.
-       The estimator's force-zero coercion on ``first_treat == 0``
-       rows with nonzero ``dose`` is implementation behavior for
-       inconsistent inputs (e.g. an accidentally-nonzero row on a
-       never-treated unit), not a methodological fallback.
+       Failure means some treated units have negative dose; see
+       routing notes below.
+
+    Routing alternatives when (1) or (5) fails:
+
+    - When (1) fails (no never-treated controls but all observed
+      doses non-negative): ``ContinuousDiD`` does not apply (Remark
+      3.1 lowest-dose-as-control is not implemented).
+      ``HeterogeneousAdoptionDiD`` IS a candidate for graded-adoption
+      designs (HAD's contract requires non-negative dose, satisfied
+      here); linear DiD with the treatment as a continuous covariate
+      is another.
+    - When (5) fails (negative treated doses):
+      ``HeterogeneousAdoptionDiD`` is **not** a fallback either —
+      HAD raises on negative post-period dose (``had.py:1450-1459``,
+      paper Section 2). Linear DiD with the treatment as a signed
+      continuous covariate is the applicable routing alternative.
+    - Re-encoding the treatment column (shifting, absolute value,
+      etc.) is an agent-side preprocessing choice that changes the
+      estimand and is not documented in REGISTRY as a supported
+      fallback; if the agent re-encodes to non-negative support,
+      both ``ContinuousDiD`` and ``HeterogeneousAdoptionDiD``
+      become candidates again on the re-encoded scale.
+    - Do **not** relabel positive- or negative-dose units as
+      ``first_treat == 0``: that triggers ``ContinuousDiD.fit()``'s
+      force-zero coercion path, which is implementation behavior
+      for inconsistent inputs (e.g., an accidentally-nonzero row on
+      a never-treated unit), not a documented routing option.
 
     The agent must still validate the supplied ``first_treat``
     column independently: it must contain at least one
diff --git a/tests/test_guides.py b/tests/test_guides.py
@@ -163,6 +163,40 @@ def test_autonomous_count_outcome_uses_asf_outcome_scale_estimand():
     )
 
 
+def test_autonomous_negative_dose_path_does_not_route_to_had():
+    """The §5.2 negative-dose counter-example must not present
+    `HeterogeneousAdoptionDiD` as a direct routing alternative
+    when `dose_min < 0`. HAD's contract requires non-negative
+    dose support and raises on negative post-period dose
+    (`had.py:1450-1459`, paper Section 2). Routing to HAD on a
+    negative-dose panel without re-encoding would steer the agent
+    into an unsupported estimator path. Guards against the wording
+    regressing back to a too-broad "HAD as fallback" framing on
+    this branch."""
+    text = get_llm_guide("autonomous")
+    # Locate counter-example #5 (negative-dose path) within §5.2.
+    sec_5_2_start = text.index("### §5.2 Continuous-dose panel")
+    sec_5_3_start = text.index("### §5.3 Count-shaped outcome")
+    sec_5_2 = text[sec_5_2_start:sec_5_3_start]
+    # The negative-dose paragraph must explicitly state HAD is NOT a
+    # routing alternative on this branch. We assert the disqualifying
+    # phrase is present; we do not forbid `HeterogeneousAdoptionDiD`
+    # entirely because the section may legitimately mention it as a
+    # candidate AFTER re-encoding.
+    assert "HAD" in sec_5_2 or "HeterogeneousAdoptionDiD" in sec_5_2, (
+        "§5.2 must mention HAD by name on the negative-dose branch "
+        "so its non-applicability can be explicitly called out."
+    )
+    assert "had.py:1450-1459" in sec_5_2, (
+        "§5.2 must cite `had.py:1450-1459` on the negative-dose "
+        "branch to anchor HAD's non-negative-dose contract (HAD "
+        "raises on negative post-period dose, paper Section 2). "
+        "Without this citation, the agent could route a "
+        "negative-dose panel directly to HAD and hit a fit-time "
+        "error."
+    )
+
+
 def test_autonomous_worked_examples_avoid_recommender_language():
     """Worked examples must mirror the rest of the guide's discipline:
     no prescriptive language in the example reasoning. Multiple paths
diff --git a/tests/test_profile_panel.py b/tests/test_profile_panel.py
