Address PR #356 CI review round 10 (1 P1 + 1 P2 + 1 P3)

Balanced-panel eligibility (P1): ContinuousDiD, EfficientDiD,
SyntheticDiD, and HeterogeneousAdoptionDiD all hard-reject unbalanced
panels at fit() time (continuous_did.py:329-338, efficient_did.py:
407-414, synthetic_did.py:399-412, had.py:1173-1188; REGISTRY.md
cross-refs). Guide updates surface this:

- New "Balanced-panel eligibility" block after §3 matrix footnotes
  names the four affected estimators and points at
  `PanelProfile.is_balanced == True` as the gate. Directs users with
  unbalanced panels to `diff_diff.prep.balance_panel()` or to a
  balance-tolerant estimator.
- §4 per-estimator bullets for all four estimators prepend or append
  the balanced-panel requirement with the specific fit() error the
  caller would otherwise hit.
- ContinuousDiD §4.7 bullet now lists THREE eligibility prerequisites
  (zero-dose controls, time-invariant dose, balanced panel) where it
  previously listed two.

Docstring (P3): profile_panel() docstring notes block updated to
match the binary-only has_always_treated semantics shipped in round
9. The old wording claimed the field fired on "strictly positive
treatment in every observed non-NaN row" across numeric types, which
no longer matches the implementation.

Tests (P2):
- Semantic guide test asserts `is_balanced` is mentioned in the guide
  and each of the four balance-sensitive estimators appears within
  400 characters of a "balanced" / "is_balanced" marker, so future
  edits cannot silently drop the eligibility gate from any of them.

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

Author: igerber

diff_diff/guides/llms-autonomous.txt

@@ -260,6 +260,16 @@ supported / out of scope; `warn` supported but with documented caveats;
   intensity as a continuous first-stage variable; not a pure
   dose-response estimator - use `ContinuousDiD` for that.
 
+**Balanced-panel eligibility.** The following estimators hard-reject
+unbalanced panels (each raises `ValueError` at `fit()` when a unit is
+missing any period): `ContinuousDiD`, `EfficientDiD`, `SyntheticDiD`,
+`HeterogeneousAdoptionDiD`. Gate these on
+`PanelProfile.is_balanced == True`; if `False`, pre-process with
+`diff_diff.prep.balance_panel()` or pick a balance-tolerant
+estimator from the remaining rows (CS/SA/dCDH/Imputation/TwoStage/
+Stacked/ETWFE all accept unbalanced input, with some caveats in their
+own docs).
+
 
 ## §4. Estimator-choice reasoning by design feature
 
@@ -317,7 +327,8 @@ estimators:
   covariates interactions; heterogeneous covariate-by-cohort effects.
 - `EfficientDiD` (Chen, Sant'Anna, Xie 2025) - asymptotically efficient
   under either `PT-All` or `PT-Post`; use `EfficientDiD.hausman_pretest`
-  to pick.
+  to pick. Requires a balanced panel (`PanelProfile.is_balanced ==
+  True`); `fit()` raises `ValueError` on unbalanced input.
 
 Diagnostic: `bacon_decompose(df, ...)` shows the weight allocation of a
 TWFE fit to 2×2 comparison types. Forbidden-comparison weight > 10% is a
@@ -382,12 +393,13 @@ worth considering.
 When `treatment_type == "continuous"`:
 
 - `ContinuousDiD` (Callaway, Goodman-Bacon, Sant'Anna 2024) -
-  continuous / dose-response treatment. **Two eligibility
+  continuous / dose-response treatment. **Three eligibility
   prerequisites**: (a) zero-dose control units must exist
   (`P(D=0) > 0`) because Remark 3.1 (lowest-dose-as-control) is not
-  yet implemented, and (b) dose must be time-invariant per unit (rule
-  out panels where `PanelProfile.treatment_varies_within_unit ==
-  True`). `fit()` raises `ValueError` in either case. Note that
+  yet implemented, (b) dose must be time-invariant per unit (rule out
+  panels where `PanelProfile.treatment_varies_within_unit == True`),
+  and (c) the panel must be balanced (`PanelProfile.is_balanced ==
+  True`). `fit()` raises `ValueError` in any of the three cases. Note that
   staggered adoption IS supported natively (adoption timing is
   expressed via the `first_treat` column, not via within-unit dose
   variation). The estimator exposes several dose-indexed targets that
@@ -411,6 +423,8 @@ but derivable from `cohort_sizes` + `has_never_treated`):
 - `SyntheticDiD` - synthetic-control-meets-DiD. Requires never-treated
   donors and sufficient pre-treatment periods (Arkhangelsky et al. 2021).
   Block treatment only: all treated units must adopt at the same time.
+  Requires a balanced panel (`PanelProfile.is_balanced == True`);
+  `fit()` raises `ValueError` and points at `balance_panel()`.
 - `TROP` - factor-model-based generalized synthetic control. Uses every
   unit untreated at period `t` as the donor pool (via the absorbing-state
   D matrix); supports staggered adoption and more complex factor
@@ -426,7 +440,9 @@ methods in the library are preferred.
 When adoption varies in strength across units (partial-adoption settings,
 intensity of exposure differs):
 
-- `HeterogeneousAdoptionDiD` - targets a Weighted Average Slope (WAS)
+- `HeterogeneousAdoptionDiD` - requires a balanced panel
+  (`PanelProfile.is_balanced == True`; `fit()` raises `ValueError`
+  when any unit is missing a period). Targets a Weighted Average Slope (WAS)
   on single-period Heterogeneous Adoption Designs where no genuinely
   untreated group exists (paper Equation 2 / Theorem 1). The
   `target_parameter` attribute on the results object is literally

diff_diff/profile.py

@@ -192,13 +192,21 @@ def profile_panel(
     ``"categorical"``; cast to ``int`` if you want binary-treatment
     profiling.
 
-    ``has_never_treated`` and ``has_always_treated`` are computed
-    generically across numeric treatment types (both binary and
-    continuous). ``has_never_treated`` fires when some unit has
-    ``treatment == 0`` in every observed non-NaN row; for continuous
-    panels this flags zero-dose controls. ``has_always_treated`` fires
-    when some unit has strictly-positive treatment in every observed
-    non-NaN row. Both are always ``False`` for ``"categorical"``.
+    ``has_never_treated`` is computed across both binary and
+    continuous numeric treatment types: some unit has ``treatment ==
+    0`` in every observed non-NaN row. For binary this flags the
+    clean-control group; for continuous this flags zero-dose controls
+    (required by ``ContinuousDiD``). Always ``False`` for
+    ``"categorical"``.
+
+    ``has_always_treated`` has binary-only semantics: some unit has
+    ``treatment == 1`` in every observed non-NaN row (no pre-treatment
+    information in the DiD sense). For ``"continuous"`` and
+    ``"categorical"`` treatment this field is always ``False``
+    regardless of dose positivity — pre-treatment periods on
+    continuous DiD are determined by the separate ``first_treat``
+    column passed to ``ContinuousDiD.fit``, not by whether the dose
+    is strictly positive.
 
     Rows with ``NaN`` in ``unit`` or ``time`` are dropped up front and
     surfaced via the ``missing_id_rows_dropped`` alert; all subsequent

tests/test_profile_panel.py

@@ -624,6 +624,38 @@ def test_guide_api_strings_resolve_against_public_api():
     assert '`"pass"` / `"warn"` / `"inconclusive"`' not in text
     assert "verdict" in text.lower()
 
+    # Balanced-panel eligibility: ContinuousDiD, EfficientDiD,
+    # SyntheticDiD, and HeterogeneousAdoptionDiD all hard-reject
+    # unbalanced panels at fit() time. The guide must surface this
+    # so agents gate these estimators on PanelProfile.is_balanced
+    # before selecting them.
+    assert "is_balanced" in text, (
+        "Guide must mention PanelProfile.is_balanced as an eligibility "
+        "check for balance-sensitive estimators"
+    )
+    for estimator in (
+        "ContinuousDiD",
+        "EfficientDiD",
+        "SyntheticDiD",
+        "HeterogeneousAdoptionDiD",
+    ):
+        idx = 0
+        found = False
+        while idx < len(text):
+            loc = text.find(estimator, idx)
+            if loc < 0:
+                break
+            window = text[max(0, loc - 400) : loc + 400]
+            if "balanced" in window.lower() or "is_balanced" in window:
+                found = True
+                break
+            idx = loc + 1
+        assert found, (
+            f"Guide must mention a balanced-panel constraint near the "
+            f"{estimator!r} bullet / row (hard-rejects unbalanced panels "
+            "at fit time)"
+        )
+
 
 def test_min_pre_post_use_per_unit_observed_support():
     """On an unbalanced panel where one treated unit is missing its