Address PR #402 R6 review (1 P3, mass-point + survey vcov caveat)

P3 mass-point + survey vcov requirement: per had.py:3495-3507 the
mass-point design rejects the default classical vcov family on the
survey_design= path with NotImplementedError (the survey path composes
Binder-TSL on the HC1-scale influence function, which targets V_HC1
rather than the classical sandwich). The Step-6 sup-t / cband snippet
in _handle_had_event_study and the HAD section in llms-full.txt
presented weighted event-study fits as a generic survey_design= path
without surfacing this constraint, so the example as written would
fail at fit time on a mass-point panel.

Both surfaces now make the requirement explicit:
- The Step-6 snippet uses HeterogeneousAdoptionDiD(vcov_type='hc1', ...)
  with an inline comment explaining that hc1 is required on mass-point
  + survey and is a no-op on the continuous designs (which use the
  CCT-2014 robust SE regardless), making it a safe default for the
  survey-aware example.
- A new "Mass-point + survey constraint" paragraph in the HAD section
  of llms-full.txt documents the same requirement and routing.

Tests added (2 new, 92 total):
- test_had_event_study_sup_t_snippet_uses_hc1_for_mass_point_survey_compatibility:
  asserts the sup-t / cband snippet either uses vcov_type='hc1' /
  robust=True or surfaces the mass-point + survey vcov requirement
  inline so agents adapting the snippet on a mass-point panel know to
  add it.
- test_llms_full_had_section_documents_mass_point_survey_vcov_requirement:
  asserts the HAD section documents the mass-point + survey vcov
  requirement (vcov_type mention paired with mass-point context).

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

Author: igerber

diff_diff/guides/llms-full.txt

@@ -657,6 +657,8 @@ es = est.fit(data, outcome_col='y', unit_col='unit',
 
 **Staggered panels.** On multi-cohort panels with `aggregate="event_study"`, `fit()` auto-filters to the last treatment cohort plus never-treated units (paper Appendix B.2) and emits a `UserWarning` naming kept/dropped counts. The estimand is then a **last-cohort-only WAS**, not a multi-cohort average. For full multi-cohort staggered support, see `ChaisemartinDHaultfoeuille`.
 
+**Mass-point + survey constraint.** When fitting `design="mass_point"` with `survey_design=` (or the deprecated `survey=` alias), `vcov_type="hc1"` (or `robust=True`) is required: the survey path composes the standard error via Binder-TSL on the HC1-scale influence function, so the default classical sandwich path raises `NotImplementedError`. Passing `vcov_type="hc1"` is a safe default on weighted survey examples since `vcov_type` is unused on the continuous designs (CCT-2014 robust SE is the only formula there).
+
 ### StackedDiD
 
 Stacked DiD estimator (Wing, Freedman & Hollingsworth 2024). Addresses TWFE bias with corrective Q-weights.

diff_diff/practitioner.py

@@ -1078,7 +1078,16 @@ def _handle_had_event_study(results: Any):
                 "from diff_diff import HeterogeneousAdoptionDiD, SurveyDesign\n"
                 "# Construct your survey design (adapt to your data):\n"
                 "sd = SurveyDesign(weights='weight_col')\n"
-                "est = HeterogeneousAdoptionDiD(n_bootstrap=999, seed=42)\n"
+                "# vcov_type='hc1' is REQUIRED on the mass-point design under\n"
+                "# survey_design= (the default classical sandwich raises\n"
+                "# NotImplementedError on the survey path because the\n"
+                "# Binder-TSL composition consumes the HC1-scale IF -\n"
+                "# see had.py:3495-3507). On the continuous designs the\n"
+                "# vcov_type kwarg is unused (CCT-2014 robust SE is the\n"
+                "# only formula), so passing vcov_type='hc1' is a no-op\n"
+                "# there and a safe default for the survey-aware example.\n"
+                "est = HeterogeneousAdoptionDiD(\n"
+                "    n_bootstrap=999, seed=42, vcov_type='hc1')\n"
                 "es = est.fit(\n"
                 "    data, outcome_col='y', unit_col='unit',\n"
                 "    time_col='t', dose_col='d',\n"

tests/test_guides.py

@@ -452,6 +452,30 @@ def test_llms_full_had_results_class_field_lists_match_real_dataclass(self):
                 f"is missing the public dataclass field {field.name!r}."
             )
 
+    def test_llms_full_had_section_documents_mass_point_survey_vcov_requirement(self):
+        # Per had.py:3495-3507 the mass-point design rejects the default
+        # classical vcov family on the survey_design= path
+        # (NotImplementedError). The HAD section must surface this
+        # requirement so an agent reading llms-full.txt and writing a
+        # weighted mass-point fit knows to pass vcov_type='hc1'
+        # explicitly. Without this caveat the documented fit() example
+        # can fail at fit time on a mass-point panel.
+        text = get_llm_guide("full")
+        had_start = text.index("### HeterogeneousAdoptionDiD")
+        had_end = text.index("### StackedDiD", had_start)
+        had_text = text[had_start:had_end]
+        # Must mention the mass-point + survey vcov requirement.
+        # Accept either explicit "vcov_type" mention near "mass" wording
+        # or the explicit "hc1" / "robust=True" pairing with mass-point.
+        lower = had_text.lower()
+        assert "vcov_type" in lower and ("mass-point" in lower or "mass_point" in lower), (
+            "HAD section must document the mass-point + survey vcov "
+            "requirement: passing vcov_type='hc1' (or robust=True) is "
+            "required on design='mass_point' under survey_design= "
+            "(per had.py:3495-3507). Without this caveat the documented "
+            "weighted fit example can raise NotImplementedError."
+        )
+
     def test_llms_full_had_variance_formula_describes_all_designs(self):
         # Per diff_diff/had.py:3585-3629, weighted mass-point fits populate
         # variance_formula in {"pweight_2sls", "survey_binder_tsl_2sls"} and

tests/test_practitioner.py

@@ -690,6 +690,46 @@ def test_handle_continuous_step_4_snippet_is_valid_python(self, mock_continuous_
             if code.strip():
                 ast.parse(code)  # raises SyntaxError on failure
 
+    def test_had_event_study_sup_t_snippet_uses_hc1_for_mass_point_survey_compatibility(
+        self, mock_had_event_study_results
+    ):
+        # Per had.py:3495-3507 the mass-point design rejects the
+        # default classical vcov family on the survey_design= path
+        # (NotImplementedError). The Step-6 sup-t snippet shows a
+        # generic weighted event-study fit; if it uses the default
+        # vcov_type a copy/paste on a mass-point panel raises at
+        # fit time. Snippet must either use vcov_type='hc1' /
+        # robust=True OR explicitly note the requirement so agents
+        # can adapt.
+        output = practitioner_next_steps(mock_had_event_study_results, verbose=False)
+        step_6_steps = [s for s in output["next_steps"] if s["baker_step"] == 6]
+        assert len(step_6_steps) >= 1
+        # Find the sup-t / cband step (sensitivity step).
+        sup_t = next(
+            (s for s in step_6_steps if "cband" in s.get("code", "")),
+            None,
+        )
+        assert sup_t is not None, "sup-t / cband step not found at baker_step=6"
+        snippet = sup_t.get("code", "")
+        # Either the snippet itself uses vcov_type='hc1' / robust=True
+        # OR it documents the requirement inline (so agents adapting
+        # the snippet on a mass-point panel know to add it).
+        ok = (
+            "vcov_type='hc1'" in snippet
+            or 'vcov_type="hc1"' in snippet
+            or "robust=True" in snippet
+            or ("mass-point" in snippet and "vcov_type" in snippet)
+            or ("mass_point" in snippet and "vcov_type" in snippet)
+        )
+        assert ok, (
+            "Sup-t / cband snippet must either use vcov_type='hc1' / "
+            "robust=True or surface the mass-point + survey vcov "
+            "requirement inline. Per had.py:3495-3507 the default "
+            "classical sandwich raises NotImplementedError on the "
+            "mass-point + survey path; the example as written would "
+            "fail at fit time on a mass-point panel."
+        )
+
     def test_had_results_dataclass_docstrings_match_weighted_mass_point_contract(self):
         # PR #402 R3 fixed the llms-full.txt field descriptions to
         # acknowledge that weighted mass-point fits populate