Address PR #356 CI review round 11 (1 P1 guide + 1 P2 test)

HeterogeneousAdoptionDiD staggered support is `partial` (per §3
matrix), but the restriction was never unpacked. Per REGISTRY.md L2281
and had.py:1100-1288, Appendix B.2 limits staggered HAD to the **last
treatment cohort plus never-treated units**. With `first_treat_col`
supplied, `fit(aggregate="event_study")` auto-filters to F_last and
emits a UserWarning naming kept/dropped counts; earlier-cohort units
are dropped. Without `first_treat_col` on a multi-cohort panel, fit()
raises a front-door ValueError pointing at ChaisemartinDHaultfoeuille
for full staggered support.

Guide updates:
- New §3 footnote on the HAD `partial` cell spelling out the last-
  cohort-only restriction, the `first_treat_col` requirement for the
  auto-filter, and the ChaisemartinDHaultfoeuille fallback.
- §4.9 HAD bullet appended with a "Staggered-timing scope is last-
  cohort-only" paragraph carrying the same contract plus the
  "last-cohort-only WAS" estimand clarification.

Tests:
- Semantic guide test asserts "last-cohort-only" (or "last cohort")
  wording, "first_treat_col" token, and ChaisemartinDHaultfoeuille as
  the fallback are all present so future guide edits cannot silently
  drop the Appendix B.2 disclosure.

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

Author: igerber

diff_diff/guides/llms-autonomous.txt

@@ -259,6 +259,15 @@ supported / out of scope; `warn` supported but with documented caveats;
 - `HeterogeneousAdoptionDiD` continuous: supports partial-adoption
   intensity as a continuous first-stage variable; not a pure
   dose-response estimator - use `ContinuousDiD` for that.
+- `HeterogeneousAdoptionDiD` staggered support is `partial`, not
+  general. Paper Appendix B.2 restricts staggered use to the
+  **last treatment cohort plus never-treated units**. With
+  `aggregate="event_study"` and a `first_treat_col` kwarg,
+  `fit()` auto-filters to `F_last = max(cohorts)` and emits a
+  `UserWarning` naming kept/dropped counts; earlier-cohort units
+  are dropped. Without `first_treat_col`, a multi-cohort panel
+  raises `ValueError`. For full staggered support that retains
+  every cohort, use `ChaisemartinDHaultfoeuille` instead.
 
 **Balanced-panel eligibility.** The following estimators hard-reject
 unbalanced panels (each raises `ValueError` at `fit()` when a unit is
@@ -459,6 +468,19 @@ intensity of exposure differs):
   pre-test battery does not and cannot validate it. Not ATT-shaped; do
   not relabel the headline as ATT in report text.
 
+  **Staggered-timing scope is last-cohort-only (Appendix B.2).**
+  HAD's staggered support is the `partial` cell in §3: on a
+  multi-cohort panel passed to `aggregate="event_study"`, `fit()`
+  auto-filters to the last treatment cohort (`F_last =
+  max(cohorts)`) plus never-treated units and emits a
+  `UserWarning` naming kept/dropped counts; earlier treated
+  cohorts are dropped. The `first_treat_col` kwarg is
+  **required** for the auto-filter to activate; without it a
+  multi-cohort panel raises `ValueError` pointing the caller at
+  `ChaisemartinDHaultfoeuille` for full staggered support. The
+  resulting estimand is a **last-cohort-only WAS**, not a
+  multi-cohort average — report it as such.
+
 ### §4.10 Repeated cross-sections (no panel structure)
 
 `profile_panel` assumes long-format panel data. When the same units are

tests/test_profile_panel.py

@@ -656,6 +656,25 @@ def test_guide_api_strings_resolve_against_public_api():
             "at fit time)"
         )
 
+    # HeterogeneousAdoptionDiD staggered support is `partial` and
+    # specifically last-cohort-only (Appendix B.2): with first_treat_col
+    # supplied, fit() auto-filters to F_last + never-treated; without
+    # first_treat_col, a multi-cohort panel raises. Guide must surface
+    # this explicitly so agents don't route a general staggered panel
+    # to HAD expecting a multi-cohort estimand.
+    assert "last-cohort-only" in text or "last cohort" in text.lower(), (
+        "Guide must name the last-cohort-only restriction on HAD "
+        "staggered support (Appendix B.2)"
+    )
+    assert "first_treat_col" in text, (
+        "Guide must mention that first_treat_col is required to activate "
+        "HAD's staggered last-cohort auto-filter"
+    )
+    assert "ChaisemartinDHaultfoeuille" in text, (
+        "Guide must point at ChaisemartinDHaultfoeuille as the fallback "
+        "for full staggered support"
+    )
+
 
 def test_min_pre_post_use_per_unit_observed_support():
     """On an unbalanced panel where one treated unit is missing its