PR #454 R3 polish: warning string accuracy + boundary convention docs

R3 verdict was ✅ Looks good with two P3 informational items:

1. Warning string accuracy: the always-treated remap warning told users
   to "pass first_treat=0 or first_treat=np.inf explicitly to silence
   this warning," but `first_treat` is the column-name argument to
   `fit()`, not a value slot. Rewrote to "recode the affected rows'
   first_treat values to 0 or np.inf in your input data before fitting"
   to point users at the actual remediation surface.

2. Test class docstring: clarified that the implementation contract
   `first_treat <= min(time)` includes the `== min(time)` boundary case
   that the paper's strict `t_i < 1` shorthand excludes, and explained
   the pragmatic rationale (units treated at the first observable
   period have no untreated cell and cannot contribute to any 2x2 DD
   as a treated cohort). Aligns with merged registry note wording and
   removes the shorthand-vs-implementation ambiguity that the R3
   reviewer flagged.

Tests: 61 pass in test_methodology_bacon.py + test_bacon.py, 3 skipped
(R parity).

Author: igerber

diff_diff/bacon.py

@@ -575,9 +575,10 @@ def fit(
                 f"(first_treat <= {min_period}, excluding sentinel values "
                 f"0 and np.inf). Remapping to U bucket per Goodman-Bacon "
                 f"(2021) footnote 11. The original first_treat column is "
-                f"preserved; remapping happens in an internal column. Pass "
-                f"first_treat=0 or first_treat=np.inf explicitly to silence "
-                f"this warning.",
+                f"preserved; remapping happens in an internal column. To "
+                f"silence this warning, recode the affected rows' "
+                f"first_treat values to 0 or np.inf in your input data "
+                f"before fitting.",
                 UserWarning,
                 stacklevel=2,
             )

tests/test_methodology_bacon.py

@@ -487,14 +487,25 @@ def _panel_with_always_treated() -> pd.DataFrame:
 
 
 class TestBaconAlwaysTreatedRemap:
-    """Goodman-Bacon (2021) footnote 11: t_i < 1 units go in U.
-
-    bacon.py automatically remaps units whose ``first_treat <= min(time)``
-    (excluding the never-treated sentinels ``0`` and ``np.inf``) via an
-    internal column (``__bacon_first_treat_internal__``), preserving the
-    user's original ``first_treat`` column unchanged. Detection uses
-    ordered-time logic on the **time axis**, so event-time-encoded
-    panels (``time ∈ [-2,..,3]``) are handled correctly.
+    """Goodman-Bacon (2021) footnote 11 with the library's first-period
+    boundary convention.
+
+    The paper's footnote 11 says units treated before the first observable
+    period (``t_i < 1`` under the paper's 1-indexed convention) belong in
+    ``U``. The library generalizes this to units whose
+    ``first_treat <= min(time)`` (i.e. includes ``first_treat == min(time)``,
+    which the paper's strict ``<`` shorthand excludes). The library
+    convention is pragmatic: units treated at the first observable period
+    have no untreated cell within the panel and cannot contribute to any
+    valid 2x2 DD as a treated cohort, so folding them into ``U`` mirrors
+    the always-treated handling. The never-treated sentinels
+    (``first_treat ∈ {0, np.inf}``) are excluded from the remap.
+
+    bacon.py applies the remap via an internal column
+    (``__bacon_first_treat_internal__``), preserving the user's original
+    ``first_treat`` column unchanged. Detection uses ordered-time logic
+    on the **time axis**, so event-time-encoded panels
+    (``time ∈ [-2,..,3]``) are handled correctly.
     """
 
     def test_warn_emitted_on_remap(self) -> None: