Address PR #402 R7 review (1 P1 + 1 P2)

P1 step-2 / Assumption 7 closure precondition: per
docs/methodology/REGISTRY.md HeterogeneousAdoptionDiD
§ "Assumption 7 / step 2 closure" + had_pretests.py:4738-4756 + 2769,
aggregate="event_study" closes paper Section 4.2 step 2 ONLY IF the
panel has at least one earlier placebo pre-period beyond the base F-1.
With only the base F-1 pre-period available (minimal 3-period
event-study, or 4-period under trends_lin=True where the consumed F-2
placebo is auto-dropped), the workflow sets pretrends_joint=None,
all_pass=False, and appends 'joint pre-trends skipped (no earlier
pre-period)' to the verdict - step 2 stays uncovered.

The previous Step-3 wording in both _handle_had and
_handle_had_event_study + the HAD Pretests intro in llms-full.txt said
generically that aggregate="event_study" closes the step-2 gap, which
is overbroad and could mislead agents on minimal valid event-study
panels. All three surfaces now make the precondition explicit AND
document the pretrends_joint=None / 'joint pre-trends skipped' fallback
verdict so agents know what to expect when the precondition fails.

P2 missing regression coverage: the prior tests locked assumption
labels and the QUG-under-survey caveat but did not lock the
earlier-pre-period precondition - that is why the overstatement
landed in the new agent-facing surfaces without tripping the existing
guide / practitioner tests.

Tests added (2 new, 94 total):
- test_had_step_3_documents_earlier_pre_period_precondition_for_step_2:
  asserts both HAD handler variants surface the 'earlier pre-period'
  / placebo precondition AND the pretrends_joint=None / 'joint
  pre-trends skipped' fallback.
- test_llms_full_had_pretests_documents_earlier_pre_period_precondition:
  same lock on the HAD Pretests section in llms-full.txt.

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

Author: igerber

diff_diff/guides/llms-full.txt

@@ -1406,7 +1406,7 @@ results = did.fit(data, outcome='y', treatment='treated', time='post')
 
 ## HAD Pretests
 
-Diagnostic pretests for the `HeterogeneousAdoptionDiD` identifying assumptions (de Chaisemartin, Ciccia, D'Haultfœuille & Knau 2026). The composite workflow `did_had_pretest_workflow` is the recommended entry point — call it before reporting WAS as causal. The workflow follows paper Section 4.2's three-step battery: **step 1** is the QUG support-infimum test (decides whether Design 1' or Design 1 applies); **step 2** is the Assumption 7 pre-trends test (joint Stute on the event-study path; explicitly NOT covered on the overall path because a single-pre-period panel cannot support the joint variant); **step 3** is the Assumption 8 linearity test (`stute_test` or `yatchew_hr_test`). On the default `aggregate="overall"` path the workflow runs steps 1 + 3 only and the returned `verdict` flags the Assumption 7 gap; pass `aggregate="event_study"` on a multi-period panel to close that gap.
+Diagnostic pretests for the `HeterogeneousAdoptionDiD` identifying assumptions (de Chaisemartin, Ciccia, D'Haultfœuille & Knau 2026). The composite workflow `did_had_pretest_workflow` is the recommended entry point — call it before reporting WAS as causal. The workflow follows paper Section 4.2's three-step battery: **step 1** is the QUG support-infimum test (decides whether Design 1' or Design 1 applies); **step 2** is the Assumption 7 pre-trends test (joint Stute on the event-study path; explicitly NOT covered on the overall path because a single-pre-period panel cannot support the joint variant); **step 3** is the Assumption 8 linearity test (`stute_test` or `yatchew_hr_test`). On the default `aggregate="overall"` path the workflow runs steps 1 + 3 only and the returned `verdict` flags the Assumption 7 gap; pass `aggregate="event_study"` on a multi-period panel **with at least one earlier placebo pre-period beyond the base `F-1`** to close that gap. With only the base `F-1` pre-period available (minimal 3-period event-study, or 4-period under `trends_lin=True` where the consumed `F-2` placebo is dropped), the workflow still sets `pretrends_joint=None`, `all_pass=False`, and appends `joint pre-trends skipped (no earlier pre-period)` to the verdict — step 2 stays uncovered.
 
 ```python
 from diff_diff import (

diff_diff/practitioner.py

@@ -865,7 +865,13 @@ def _handle_had(results: Any):
                 "path - a single pre-period cannot support the joint "
                 "Stute variant - and the returned verdict explicitly "
                 "flags that gap. To close step 2, refit on a multi-period "
-                "panel with aggregate='event_study'. On survey-weighted "
+                "panel with aggregate='event_study' AND verify the panel "
+                "has at least one earlier placebo pre-period beyond F-1; "
+                "if only the base pre-period F-1 is available, the "
+                "workflow still sets pretrends_joint=None, all_pass=False, "
+                "and a 'joint pre-trends skipped (no earlier pre-period)' "
+                "verdict suffix - in that case step 2 stays uncovered "
+                "even on the event-study path. On survey-weighted "
                 "fits (survey_design= / survey= / weights=) the workflow "
                 "skips QUG with a UserWarning (permanent Phase 4.5 C0 "
                 "deferral - extreme order statistics are not smooth "
@@ -1010,9 +1016,15 @@ def _handle_had_event_study(results: Any):
                 "On multi-period unweighted panels, did_had_pretest_workflow "
                 "with aggregate='event_study' runs QUG plus joint Stute "
                 "pre-trends plus joint homogeneity-linearity Stute. The "
-                "joint Stute variants close the paper Section 4.2 step-2 "
-                "gap that the overall path explicitly flags as deferred. "
-                "On survey-weighted fits (survey_design= / survey= / "
+                "joint Stute pre-trends variant closes the paper Section "
+                "4.2 step-2 gap ONLY IF the panel carries at least one "
+                "earlier placebo pre-period beyond the base F-1. With "
+                "only the base F-1 pre-period present (e.g. a minimal "
+                "valid 3-period event-study fit, or a 4-period fit under "
+                "trends_lin=True where the consumed F-2 placebo gets "
+                "dropped), pretrends_joint=None, all_pass=False, and the "
+                "verdict carries 'joint pre-trends skipped (no earlier "
+                "pre-period)' - step 2 stays uncovered. On survey-weighted fits (survey_design= / survey= / "
                 "weights=) the workflow skips QUG with a UserWarning "
                 "(permanent Phase 4.5 C0 deferral) and returns a "
                 "linearity-conditional verdict only - so step 1 coverage "

tests/test_guides.py

@@ -547,6 +547,30 @@ def test_llms_practitioner_step_4_distinguishes_had_from_continuous(self):
             "ContinuousDiD routing."
         )
 
+    def test_llms_full_had_pretests_documents_earlier_pre_period_precondition(self):
+        # Same precondition as the practitioner test: per
+        # docs/methodology/REGISTRY.md HeterogeneousAdoptionDiD
+        # § "Assumption 7 / step 2 closure" + had_pretests.py:4738-4756 +
+        # 2769, aggregate="event_study" closes step 2 ONLY IF the
+        # panel carries at least one earlier placebo pre-period beyond
+        # the base F-1. The HAD Pretests section in llms-full.txt must
+        # document this precondition so agents do not assume any
+        # multi-period event-study fit closes step 2.
+        text = get_llm_guide("full")
+        pretests_start = text.index("## HAD Pretests")
+        pretests_end = text.index("## Honest DiD", pretests_start)
+        pretests_block = text[pretests_start:pretests_end]
+        lower = pretests_block.lower()
+        assert "earlier" in lower and ("pre-period" in lower or "placebo" in lower), (
+            "HAD Pretests section must document the 'earlier pre-period' "
+            "precondition for step-2 closure on the event-study path."
+        )
+        assert "skipped" in lower or "pretrends_joint=none" in lower, (
+            "HAD Pretests section must surface the "
+            "'joint pre-trends skipped' / pretrends_joint=None fallback "
+            "when no earlier pre-period exists."
+        )
+
     def test_llms_full_had_pretests_assumption_labels_correct(self):
         # Per docs/methodology/REGISTRY.md HeterogeneousAdoptionDiD
         # § "Assumptions / Theorems / Estimators":

tests/test_practitioner.py

@@ -779,6 +779,43 @@ def test_had_results_dataclass_docstrings_match_weighted_mass_point_contract(sel
             "for mass-point fits."
         )
 
+    def test_had_step_3_documents_earlier_pre_period_precondition_for_step_2(
+        self, mock_had_results, mock_had_event_study_results
+    ):
+        # Per docs/methodology/REGISTRY.md HeterogeneousAdoptionDiD
+        # § "Assumption 7 / step 2 closure" + had_pretests.py:4738-4756 +
+        # 2769: aggregate="event_study" closes step 2 ONLY IF the panel
+        # carries at least one earlier placebo pre-period beyond the
+        # base F-1. With only F-1 available the workflow sets
+        # pretrends_joint=None, all_pass=False, and the verdict carries
+        # 'joint pre-trends skipped (no earlier pre-period)'. Both HAD
+        # handler variants must surface this precondition - otherwise
+        # agents reading the guidance can think any multi-period
+        # event-study fit closes step 2 when it does not.
+        for fixture in (mock_had_results, mock_had_event_study_results):
+            output = practitioner_next_steps(fixture, verbose=False)
+            step_3_steps = [s for s in output["next_steps"] if s["baker_step"] == 3]
+            assert len(step_3_steps) == 1
+            text = (step_3_steps[0].get("why", "") + " " + step_3_steps[0].get("code", "")).lower()
+            # Must mention "earlier" pre-period / placebo precondition.
+            assert "earlier" in text and ("pre-period" in text or "placebo" in text), (
+                "Step-3 text must mention the 'earlier pre-period' "
+                "precondition for closing Assumption 7 / step 2 on the "
+                "event-study path. With only the base F-1 pre-period "
+                "the workflow returns pretrends_joint=None and the "
+                "verdict carries 'joint pre-trends skipped (no earlier "
+                "pre-period)' - step 2 stays uncovered."
+            )
+            # Must mention the skip-fallback verdict so agents know
+            # what to expect when the precondition fails.
+            assert "skipped" in text or "pretrends_joint=none" in text, (
+                "Step-3 text must surface the 'joint pre-trends skipped' "
+                "/ pretrends_joint=None fallback when no earlier "
+                "pre-period exists - otherwise agents cannot tell "
+                "whether step 2 was actually covered on a minimal "
+                "event-study fit."
+            )
+
     def test_had_step_3_flags_qug_under_survey_deferral(
         self, mock_had_results, mock_had_event_study_results
     ):