Address PR #366 CI review round 4 (2 P1 + 1 P2): WooldridgeDiD Poisson estimand wording + is_count_like non-negativity guard

P1 #1 (Wooldridge Poisson estimand wording):
The guide §4.11 and §5.3 worked example described
`WooldridgeDiD(method="poisson")`'s `overall_att` as a
"multiplicative effect" / "log-link effect" / "proportional change"
to be reported. Verified against `wooldridge.py:1225`
(`att = _avg(mu_1 - mu_0, cell_mask)`) and
`_reporting_helpers.py:262-281` (registered estimand: "ASF-based
average from Wooldridge ETWFE ... average-structural-function (ASF)
contrast between treated and counterfactual untreated outcomes ...
on the natural outcome scale"): the actual quantity is
`E[exp(η_1)] - E[exp(η_0)]`, an outcome-scale DIFFERENCE, not a
multiplicative ratio. An agent following the previous wording would
misreport the headline scalar.

Rewrote both surfaces to:
- Describe the estimand as an ASF-based outcome-scale difference,
  citing `wooldridge.py:1225` and Wooldridge (2023) +
  REGISTRY.md §WooldridgeDiD nonlinear / ASF path.
- Explicitly note the headline `overall_att` is a difference on the
  natural outcome scale, NOT a multiplicative ratio.
- Mention that a proportional / percent-change interpretation can
  be derived post-hoc as `overall_att / E[Y_0]` but is not the
  estimator's reported scalar.

Added `test_autonomous_count_outcome_uses_asf_outcome_scale_estimand`
in `tests/test_guides.py`: extracts §4.11 and §5.3 blocks, asserts
forbidden phrases ("multiplicative effect under qmle", "estimates
the multiplicative effect", "multiplicative (log-link) effect",
"report the multiplicative effect", "report the multiplicative")
do NOT appear, and asserts §5.3 explicitly contains "ASF" and
"outcome scale" so future edits cannot silently weaken the
description.

P1 #2 (`is_count_like` non-negativity guard):
The `is_count_like` heuristic gated on integer-valued + has-zeros +
right-skewed + > 2 distinct values, but did NOT exclude negative
support. Verified against `wooldridge.py:1105-1109`: Poisson method
hard-rejects `y < 0` with `ValueError`. Without a value_min >= 0
guard, a right-skewed integer outcome with zeros and some negatives
would set `is_count_like=True` and steer an agent toward an
estimator that then refuses to fit.

Added `value_min >= 0.0` to the heuristic and explained the
non-negativity gate in the docstring + autonomous guide §2 field
reference (now reads
"is_integer_valued AND pct_zeros > 0 AND skewness > 0.5 AND
n_distinct_values > 2 AND value_min >= 0"). The guide also notes
that the gate exists specifically to align the routing signal with
WooldridgeDiD Poisson's hard non-negativity requirement.

Added `test_outcome_shape_count_like_excludes_negative_support` in
`tests/test_profile_panel.py` covering a Poisson-distributed outcome
with a small share of negative integers spliced in: asserts
`is_count_like=False` despite the other four conditions firing.

P2 (test coverage for both P1s):
Both regressions above guard the new contracts. The guide test
guards the wording surface; the profile test guards the heuristic.

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

Author: igerber

diff_diff/guides/llms-autonomous.txt

@@ -187,10 +187,15 @@ view. Every field below appears as a top-level key in that dict.
       (covers integer dtype and floats that happen to be integer-valued).
     - `is_count_like: bool` - heuristic for count-shaped outcomes:
       `is_integer_valued AND pct_zeros > 0 AND skewness > 0.5 AND
-      n_distinct_values > 2`. When `True`, an OLS DiD on the raw
-      outcome may have well-behaved point estimates but questionable
-      asymptotic SEs; consider `WooldridgeDiD` (QMLE Poisson family)
-      or document the choice. See §5.3 for a worked example.
+      n_distinct_values > 2 AND value_min >= 0`. When `True`, an OLS
+      DiD on the raw outcome may have well-behaved point estimates
+      but questionable asymptotic SEs; consider
+      `WooldridgeDiD(method="poisson")` (QMLE), which estimates the
+      overall ATT as an ASF-based outcome-scale difference (NOT a
+      multiplicative ratio) and rejects negative outcomes at fit
+      time. The non-negativity gate aligns the routing signal with
+      that hard requirement so the estimator will accept the panel.
+      See §5.3 for a worked example.
     - `is_bounded_unit: bool` - all non-NaN values lie in `[0, 1]`.
       When `True` and the linear-DiD point estimate is near the
       boundary of feasible support, interpret with care (the linear
@@ -618,15 +623,22 @@ count-shaped outcome (e.g., number of incidents per unit-period) for
 which linear DiD point estimates are unbiased but asymptotic SEs may
 mislead. `PanelProfile.outcome_shape` exposes the relevant facts:
 
-- `outcome_shape.is_count_like == True` (integer-valued, has zeros,
-  right-skewed, more than two distinct values) - linear-OLS DiD on the
-  raw count works for the point estimate but inference may be off.
-  Consider `WooldridgeDiD` (QMLE Poisson) which estimates the
-  multiplicative effect directly and gives correctly-calibrated SEs
-  under quasi-MLE. Linear-OLS DiD with cluster-robust SEs remains a
-  defensible choice when the count is large enough that the normal
-  approximation holds; the shape field flags the consideration, not a
-  rule. §5.3 walks through this pattern with a concrete profile.
+- `outcome_shape.is_count_like == True` (integer-valued, non-negative,
+  has zeros, right-skewed, more than two distinct values) - linear-OLS
+  DiD on the raw count works for the point estimate but asymptotic SEs
+  assume normal-shaped errors that a right-skewed distribution can
+  violate. Consider `WooldridgeDiD(method="poisson")`, which estimates
+  the overall ATT as an ASF-based outcome-scale difference (per-cell
+  average of `E[exp(η_1)] - E[exp(η_0)]`, Wooldridge 2023; see
+  REGISTRY.md §WooldridgeDiD nonlinear / ASF path) under QMLE, with
+  correctly-calibrated SEs. The headline `overall_att` is a difference
+  on the outcome scale, NOT a multiplicative ratio; a proportional
+  interpretation can be derived post-hoc as `overall_att / E[Y_0]` if
+  desired but is not the estimator's reported scalar. Linear-OLS DiD
+  with cluster-robust SEs remains a defensible choice when the count
+  is large enough that the normal approximation holds; the shape field
+  flags the consideration, not a rule. §5.3 walks through this pattern
+  with a concrete profile.
 - `outcome_shape.is_bounded_unit == True` (values in `[0, 1]`,
   e.g. a proportion) - linear DiD can produce predictions outside
   `[0, 1]` and inference at the boundary is questionable. No
@@ -798,18 +810,26 @@ Reasoning chain:
 
 1. Same staggered-binary narrowing as §5.1 (CS/SA/dCDH/Imputation/
    TwoStage/Stacked/ETWFE/EfficientDiD applicable).
-2. `outcome_shape.is_count_like == True` -> linear-OLS DiD on the
-   raw count gives unbiased point estimates of the additive effect
-   but its asymptotic SEs assume normal-shaped errors, which a
-   right-skewed count distribution violates. `WooldridgeDiD`
-   (`method="poisson"`) estimates the multiplicative
-   (log-link) effect under QMLE with correct asymptotic SEs, and
-   maps onto the staggered design natively.
-3. Decision: fit `WooldridgeDiD(method="poisson")` for the
-   primary estimate; report the multiplicative effect (proportional
-   change) rather than the additive effect. Optionally fit a linear
-   DiD as a robustness check and document which scale the headline
-   uses.
+2. `outcome_shape.is_count_like == True` AND
+   `outcome_shape.value_min >= 0` -> linear-OLS DiD on the raw count
+   gives unbiased point estimates but its asymptotic SEs assume
+   normal-shaped errors that a right-skewed count distribution
+   violates. `WooldridgeDiD(method="poisson")` (QMLE) estimates the
+   overall ATT as an ASF-based outcome-scale difference: the per-cell
+   average of `E[exp(η_1)] - E[exp(η_0)]` (Wooldridge 2023; see
+   REGISTRY.md §WooldridgeDiD nonlinear / ASF path), with
+   correctly-calibrated SEs under quasi-MLE. The Poisson fitter
+   hard-rejects negative outcomes (`y < 0` raises `ValueError` at
+   line ~1105 of `wooldridge.py`), which is why `is_count_like` gates
+   on `value_min >= 0`.
+3. Decision: fit `WooldridgeDiD(method="poisson")` for the primary
+   estimate; report the headline `overall_att` as a difference on the
+   outcome scale (the same units as the count), not as a
+   multiplicative ratio. A proportional / percent-change reading can
+   be derived post-hoc by dividing the ATT by an estimate of
+   `E[Y_0]`, but the estimator's reported scalar is the difference.
+   Optionally fit a linear DiD as a robustness check and document
+   that both estimands are on the same scale.
 4. Caveat: when the outcome includes structural zeros that violate
    Poisson conditional moments (overdispersion), consider negative
    binomial QMLE or a hurdle model; the current suite does not

diff_diff/profile.py

@@ -637,12 +637,20 @@ def _compute_outcome_shape(valid: pd.Series, outcome_dtype_kind: str) -> Optiona
             skewness = float(m3 / (std**3))
             excess_kurtosis = float(m4 / (m2**2) - 3.0)
 
+    # Non-negativity is part of the contract: `is_count_like == True`
+    # is the routing signal toward `WooldridgeDiD(method="poisson")`,
+    # which hard-rejects negative outcomes at fit time
+    # (`wooldridge.py:1105` raises `ValueError` on `y < 0`). Without the
+    # `value_min >= 0` guard, a right-skewed integer outcome with zeros
+    # and some negatives could set `is_count_like=True` and steer an
+    # agent toward an estimator that will then refuse to fit.
     is_count_like = bool(
         is_integer_valued
         and pct_zeros > 0.0
         and skewness is not None
         and skewness > 0.5
         and n_distinct > 2
+        and value_min >= 0.0
     )
 
     return OutcomeShape(

tests/test_guides.py

@@ -83,6 +83,62 @@ def test_autonomous_contains_worked_examples_section():
     )
 
 
+def test_autonomous_count_outcome_uses_asf_outcome_scale_estimand():
+    """§4.11 and §5.3 must describe `WooldridgeDiD(method="poisson")`'s
+    `overall_att` as an ASF-based outcome-scale difference (matching the
+    estimator at `wooldridge.py:1225` and the reporting helper at
+    `_reporting_helpers.py:262-281`), NOT as a multiplicative /
+    proportional / log-link effect. An agent following an example that
+    described the headline as "multiplicative" would misreport the
+    scalar - the library's reported `overall_att` is `E[exp(η_1)] -
+    E[exp(η_0)]`, a difference on the natural outcome scale.
+
+    Guards against regressing the wording back to "multiplicative
+    effect" / "proportional change" framing. Multiplicative
+    interpretations may appear in the guide as a clearly-marked
+    derived post-hoc reading, but never as the description of the
+    estimator's reported `overall_att`."""
+    text = get_llm_guide("autonomous")
+    # Locate §4.11 and §5.3 blocks; check that within them the Poisson
+    # path is described with ASF / outcome-scale wording, NOT as the
+    # estimator's reported scalar being multiplicative or proportional.
+    sec_4_11_start = text.index("### §4.11 Outcome-shape considerations")
+    sec_4_11_end = text.index("## §5. Worked examples")
+    sec_4_11 = text[sec_4_11_start:sec_4_11_end]
+
+    sec_5_3_start = text.index("### §5.3 Count-shaped outcome")
+    sec_5_3_end = text.index("## §6. Post-fit validation utilities")
+    sec_5_3 = text[sec_5_3_start:sec_5_3_end]
+
+    forbidden_phrases = (
+        "multiplicative effect under qmle",
+        "estimates the multiplicative effect",
+        "multiplicative (log-link) effect",
+        "report the multiplicative effect",
+        "report the multiplicative",
+    )
+    for section_name, body in (("§4.11", sec_4_11), ("§5.3", sec_5_3)):
+        lowered = body.lower()
+        for phrase in forbidden_phrases:
+            assert phrase not in lowered, (
+                f"{section_name} of the autonomous guide describes the "
+                f"WooldridgeDiD Poisson `overall_att` with the phrase "
+                f"{phrase!r}; the estimator returns an ASF-based "
+                f"outcome-scale difference (`E[exp(η_1)] - E[exp(η_0)]`), "
+                f"not a multiplicative ratio. See `wooldridge.py:1225` "
+                f"and `_reporting_helpers.py:262-281`."
+            )
+
+    # Positive: each block must explicitly anchor the estimand to the
+    # ASF / outcome-scale framing so future edits can't silently weaken
+    # the description.
+    assert "ASF" in sec_5_3, "§5.3 must reference the ASF interpretation"
+    assert "outcome scale" in sec_5_3.lower(), (
+        "§5.3 must label the WooldridgeDiD `overall_att` as an "
+        "outcome-scale quantity to prevent multiplicative-ratio drift."
+    )
+
+
 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

tests/test_profile_panel.py

@@ -927,6 +927,50 @@ def test_outcome_shape_binary_outcome_not_count_like():
     assert shape.n_distinct_values == 2
 
 
+def test_outcome_shape_count_like_excludes_negative_support():
+    """`is_count_like` is the routing signal toward
+    `WooldridgeDiD(method="poisson")`, which raises `ValueError` on
+    negative outcomes (`wooldridge.py:1105`). The heuristic must
+    therefore gate on `value_min >= 0`: a right-skewed integer outcome
+    with zeros AND some negative values must NOT set `is_count_like`,
+    even though the other four conditions (integer-valued, has zeros,
+    skewness > 0.5, > 2 distinct values) are satisfied. Otherwise the
+    autonomous-guide §5.3 reasoning chain would steer agents toward an
+    estimator that will then refuse to fit the panel."""
+    rng = np.random.default_rng(37)
+    first_treat = {u: 2 for u in range(101, 201)}
+
+    # Mix Poisson with a small share of negative integers - integer-valued,
+    # has zeros (Poisson(0.5) yields ~60% zeros), and right-skewed; but
+    # value_min < 0 should kill is_count_like.
+    def _outcome_fn(u, t, tr, _rng):
+        base = int(rng.poisson(0.5 + 0.2 * tr))
+        # 5% of cells become a small negative integer, e.g. -1 or -2.
+        if rng.random() < 0.05:
+            return -int(rng.integers(1, 3))
+        return base
+
+    df = _make_panel(
+        n_units=200,
+        periods=range(0, 4),
+        first_treat=first_treat,
+        outcome_fn=_outcome_fn,
+    )
+    profile = profile_panel(df, unit="u", time="t", treatment="tr", outcome="y")
+    shape = profile.outcome_shape
+    assert shape is not None
+    assert shape.value_min < 0, "fixture must include some negative outcomes"
+    assert shape.is_integer_valued is True
+    assert shape.pct_zeros > 0.1
+    assert shape.skewness is not None
+    assert shape.is_count_like is False, (
+        "is_count_like must be False when value_min < 0; otherwise an "
+        "agent following the §5.3 worked example would route the panel "
+        "to WooldridgeDiD(method='poisson'), which raises ValueError on "
+        "negative outcomes."
+    )
+
+
 def test_outcome_shape_continuous_normal():
     """Normally-distributed float outcome must have is_integer_valued=False,
     is_count_like=False, is_bounded_unit=False (signed values exit [0,1])."""