PR #454 R4 polish: replicate-weight skip path + wrapper docstring mirror

R4 verdict was Looks good with two P3 polish items (plus the standing
R-parity-goldens follow-up, which is tracked and non-blocking). Both
addressed:

1. Replicate-weight skip path (P3 Code Quality): the R1 skip-vs-error
   fix on `DiagnosticReport._check_bacon` only handled the within-unit-
   varying-survey ValueError case. Replicate-weight survey designs
   raise NotImplementedError from `BaconDecomposition.fit()` and were
   still falling through to the generic exception handler as
   `status="error"`. Added an `except NotImplementedError` branch that
   returns a structured skip with a reason naming the supported
   alternative (TSL-based design via SurveyDesign + precomputed=
   escape hatch). New regression at
   `TestBaconSurveyDesignNarrowing::test_diagnostic_report_skips_with_structured_reason_on_replicate_weights`.

2. Wrapper docstring mirror (P3 Documentation/Tests): the public
   `bacon_decompose()` and `TwoWayFixedEffects.decompose()` wrappers
   had short `first_treat` parameter descriptions that mentioned only
   the 0/np.inf never-treated convention, omitting the new
   always-treated remap + sentinel reservation contract that lives in
   `BaconDecomposition.fit()`. Mirrored the expanded contract into
   both wrappers (with a pointer to the full docstring on the class)
   so users reading wrapper help see the behavior change.

Tests: 62 pass in test_methodology_bacon.py + test_bacon.py (one new
regression), 3 skipped (R parity); 98 pass across the broader
bacon/decompose surface.

Author: igerber

diff_diff/bacon.py

@@ -1250,8 +1250,19 @@ def bacon_decompose(
     time : str
         Name of time period column.
     first_treat : str
-        Name of column indicating when unit was first treated.
-        Use 0 (or np.inf) for never-treated units.
+        Name of column indicating when unit was first treated. The
+        values ``0`` and ``np.inf`` are **reserved as never-treated
+        sentinels**; a real treatment cohort with ``first_treat == 0``
+        would be folded into ``U`` and should be re-labeled to a
+        non-sentinel value before fitting. Units whose ``first_treat``
+        is at or before the first observable period
+        (``first_treat <= min(time)``, excluding the sentinels) are
+        automatically remapped to the ``U`` (untreated) bucket per
+        Goodman-Bacon (2021) footnote 11, with a ``UserWarning``. See
+        ``BaconDecomposition.fit()`` for the full contract and
+        ``BaconDecompositionResults.n_always_treated_remapped`` for the
+        count. The user's original ``first_treat`` column is preserved
+        unchanged.
     weights : str, default="exact"
         Weight calculation method:
 

diff_diff/diagnostic_report.py

@@ -1774,6 +1774,31 @@ def _check_bacon(self) -> Dict[str, Any]:
                 "status": "error",
                 "reason": f"bacon_decompose raised {type(exc).__name__}: {exc}",
             }
+        except NotImplementedError as exc:
+            # PR #454 R4 P3: ``BaconDecomposition.fit()`` raises
+            # ``NotImplementedError`` for replicate-weight survey designs
+            # (bacon.py rejects them because Bacon is a diagnostic that
+            # does not compute replicate-based variance). Match the
+            # within-unit-varying skip pattern above: emit a structured
+            # skip naming the ``precomputed={'bacon': ...}`` escape hatch
+            # so survey-backed reports with replicate-weight designs
+            # produce an actionable skip rather than an opaque
+            # ``status="error"`` block.
+            return {
+                "status": "skipped",
+                "reason": (
+                    "Survey design uses replicate weights, which the "
+                    "Bacon decomposition does not support (bacon is a "
+                    "diagnostic and does not compute replicate-based "
+                    "variance). To populate this section, run "
+                    "``bacon_decompose(data, ..., "
+                    "survey_design=SurveyDesign(weights=..., strata=..., "
+                    "psu=..., fpc=...))`` with a TSL-based design and "
+                    "pass via "
+                    "``DiagnosticReport(..., precomputed={'bacon': result})``. "
+                    f"Rejection detail: {exc}"
+                ),
+            }
         except Exception as exc:  # noqa: BLE001
             return {
                 "status": "error",

diff_diff/twfe.py

@@ -702,7 +702,19 @@ def decompose(
             Name of time period column.
         first_treat : str
             Name of column indicating when each unit was first treated.
-            Use 0 (or np.inf) for never-treated units.
+            The values ``0`` and ``np.inf`` are **reserved as
+            never-treated sentinels**; a real treatment cohort with
+            ``first_treat == 0`` would be folded into ``U`` and should
+            be re-labeled to a non-sentinel value before fitting. Units
+            whose ``first_treat`` is at or before the first observable
+            period (``first_treat <= min(time)``, excluding the
+            sentinels) are automatically remapped to the ``U``
+            (untreated) bucket per Goodman-Bacon (2021) footnote 11
+            with a ``UserWarning``. See ``BaconDecomposition.fit()`` for
+            the full contract and
+            ``BaconDecompositionResults.n_always_treated_remapped`` for
+            the count. The user's original ``first_treat`` column is
+            preserved unchanged.
         weights : str, default="exact"
             Weight calculation method:
 

tests/test_methodology_bacon.py

@@ -1067,6 +1067,45 @@ def test_explicit_approximate_accepts_time_varying_weights(self) -> None:
         assert abs(total - 1.0) < 0.01
         assert np.isfinite(results.twfe_estimate)
 
+    def test_diagnostic_report_skips_with_structured_reason_on_replicate_weights(
+        self,
+    ) -> None:
+        """PR #454 R4 P3 regression: ``DiagnosticReport._check_bacon``
+        emits ``status="skipped"`` (not ``"error"``) when the survey
+        design uses replicate weights, which Bacon rejects with
+        ``NotImplementedError`` upstream. The skip reason names the
+        ``precomputed={'bacon': ...}`` escape hatch and points users at
+        a TSL-based survey design as the supported alternative.
+        """
+        from diff_diff import DiagnosticReport, SurveyDesign
+
+        df, _ = self._time_varying_survey_panel()
+        df["rep_w1"] = 1.0
+        df["rep_w2"] = 1.0
+        sd_rep = SurveyDesign(
+            weights="w",
+            replicate_weights=["rep_w1", "rep_w2"],
+            replicate_method="BRR",
+        )
+
+        class _Stub:
+            pass
+
+        dr = DiagnosticReport(
+            _Stub(),
+            data=df,
+            outcome="y",
+            unit="unit",
+            time="time",
+            first_treat="first_treat",
+            survey_design=sd_rep,
+        )
+        block = dr._check_bacon()
+        assert block["status"] == "skipped"
+        reason = block["reason"]
+        assert "replicate weights" in reason
+        assert "precomputed" in reason
+
     def test_diagnostic_report_skips_with_structured_reason_on_time_varying_survey(
         self,
     ) -> None: