igerber · igerber · Aug 8, 2026 · Aug 8, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,7 +7,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **TwoWayFixedEffects event-study mode** (v4 program Phase 3(a); ledger
+  row [M-010] shimmed): `TWFE().fit(..., event_study=True, time="period",
+  spec="within"|"pooled", reference_period=None, post_periods=[...])`
+  estimates per-period treatment effects and returns the unified
+  `EventStudyResults` surface natively (`source="TwoWayFixedEffects"`,
+  plus two new container provenance fields: the authoritative
+  `post_periods` calendar partition and `estimation_spec` - ledger row
+  [M-092] amendment). `spec="within"` (default) estimates the unit-FE
+  event study; `spec="pooled"` reproduces the MultiPeriodDiD design
+  exactly (the only spec valid for repeated cross-sections - it is the
+  migration target for 3.x MultiPeriodDiD fits, reproducing their
+  numbers under matched cluster settings and unconditionally without a
+  unit id). Point estimates coincide across the two specs only in the
+  restricted equivalence case (balanced panel, no covariates,
+  simultaneous adoption); with unbalanced panels or covariates the
+  unit-FE projection changes point estimates too. Event-study calls
+  pass `time=` (calendar) and `unit=` as keywords; `post_periods=` is
+  REQUIRED in event-study mode (the treatment boundary is not observable
+  from a time-invariant ever-treated indicator, so MultiPeriodDiD's
+  midpoint default - last half of the calendar - is a silent guess and
+  is deliberately not carried over; MultiPeriodDiD itself keeps it
+  through 3.9); the mode carries
+  TWFE's inference stack from day one - unit auto-cluster (with the
+  static carve-outs: dropped on Conley and for explicit one-way
+  analytical families, never injected as a survey PSU) - and
+  `inference="wild_bootstrap"` raises an explicit `ValueError` (the
+  wild cluster bootstrap covers the static ATT only; MultiPeriodDiD's
+  silent analytical fallback is deliberately not carried into the
+  merged mode). HonestDiD, PreTrendsPower, and `plot_event_study`
+  consume the new surface (dedicated calendar container routes with
+  native-route parity; HonestDiD scoped to chronologically-partitioned
+  surfaces per the Rambachan-Roth restriction geometry).
+
+### Changed
+- **DiagnosticReport and BusinessReport explicitly reject
+  `EventStudyResults` inputs** (previously: DiagnosticReport silently
+  produced a zero-check report via an empty type-keyed applicability
+  set, and BusinessReport rendered an all-null scalar headline). Both
+  errors steer to the fitted estimator's scalar results; admission of
+  event-study surfaces is tracked in TODO.md.
+
 ### Deprecated
+- **MultiPeriodDiD + the EventStudy alias** (v4 program Phase 3(a);
+  ledger rows [M-010] shimmed, [M-060]): constructing `MultiPeriodDiD`
+  (or `EventStudy` - the same class object) emits a `FutureWarning`
+  naming the successor; both are removed in 4.0. Migration:
+  `TwoWayFixedEffects().fit(..., event_study=True, spec="pooled")`
+  reproduces the MultiPeriodDiD design; the default `spec="within"`
+  adds unit fixed effects (standard errors and, on unbalanced or
+  covariate designs, point estimates shift - the documented estimate
+  change). Behavior of fitted MultiPeriodDiD results is unchanged
+  through 3.9.
+- **TwoWayFixedEffects static `fit(time=)` renamed to `post=`** (ledger
+  row [M-082] shimmed): the static 0/1 dummy parameter is `post=`; the
+  old keyword still works through 3.9 with a `FutureWarning` (from 4.0,
+  `time=` means the event-study calendar column only - the 4.0 semantic
+  enforcement is row [M-083]). Positional callers are unaffected
+  (`post` occupies the old slot).
 - **The 8 estimator convenience wrappers + the CDiD/Gardner/Stacked alias
   diet; new `SCM` alias** (v4 program 2(d) PR-A; ledger rows
   [M-070]..[M-077] shimmed, [M-062] + [M-135] done, notes amendments to

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -174,8 +174,10 @@ A new parameter is only complete when it is:
 - applied in **every** aggregation mode — `simple`, `event_study`, and `group`
 - applied in the **bootstrap/inference** paths, not just the analytical one
 - reflected on the result object, so `to_dict()`/`summary()` do not misreport it
-- propagated to the estimators that inherit it: `TwoWayFixedEffects` and
-  `MultiPeriodDiD` define no `__init__` of their own, so they inherit a new
+- propagated to the estimators that inherit it: `TwoWayFixedEffects` defines
+  no `__init__` of its own, and `MultiPeriodDiD`'s 3.9 deprecation shim
+  forwards via `super().__init__(*args, **kwargs)` with an import-time
+  `__signature__` mirror - so both inherit a new
   `DifferenceInDifferences` constructor parameter automatically;
   `SyntheticDiD` defines its OWN signature (it forwards only
   `robust`/`cluster`/`alpha` to `super().__init__`), so a new parent

diff --git a/DEFERRED.md b/DEFERRED.md
@@ -20,6 +20,7 @@ provenance and AI-review deviation-documentation: a row here (or in
 
 | Issue | Location | PR | Priority |
 |-------|----------|----|----------|
+| HonestDiD non-chronological declared partitions (native `MultiPeriodDiDResults` route): the Rambachan-Roth restriction matrices are built POSITIONALLY over the concatenated declared pre/post lists assuming one chronological boundary, but the native route accepts non-suffix `post_periods` / non-last-pre references and returns bounds whose restriction system does not match the Registry equations (pre-existing; surfaced by the Phase 3(a) calendar-route review, which fails closed instead). Fix = transform the declared partition into boundary form where a valid mapping exists, else reject on the native route too - needs the restriction-geometry derivation. REGISTRY HonestDiD Note records the limitation. | `diff_diff/honest_did.py` | 3(a) | Medium |
 | `PlaceboTests` `boundary_gap` — a permutation randomization-inference margin (SE-audit item (b)); NOT computed anywhere in code today, so this is a new feature + result field, not a coverage lock. **User-locked 2026-07-09: defer until a derivation/paper source exists** — do not design or implement from scratch. | `tests/test_methodology_placebo.py`, `diff_diff/diagnostics.py` | SE-audit | Low |
 | TwoStageDiD honest/pretrends container admission DEFERRED (decision revised from "widen" during the 2(b) PR-3b plan review): analytical fits carry the joint Gardner-GMM event-study covariance (M-092), but the pre-period coefficients are stage-1 residual MEANS — the reference horizon is dropped from the no-intercept Stage-2 design and the zero anchor row appended mechanically — not contrasts against a reference period, while HonestDiD's Δ^RM/Δ^SD arithmetic hard-codes the `delta_0 = 0` normalization into its boundary/bridge constraints. Admission needs either a Stage-2 re-estimation with the reference horizon in the design or a derived residual-to-reference normalization mapping (+ its variance transform). Both consumers' TypeErrors state the deferral; see the REGISTRY TwoStageDiD Note (d). | `diff_diff/honest_did.py`, `diff_diff/pretrends.py`, `diff_diff/two_stage_aggregation.py` | 2(b) PR-3b | Low |
 | CBWSDID covariate balancing (`StackedDiD(balance="entropy")`) v1 supports only balanced event windows + `weighting="aggregate"`; unbalanced/ragged panels fail closed (unit-count vs observation-count corrector convention unresolved off balanced panels). Matching-based balancing and the repeated `0→1`/`1→0` episode extension are also deferred. Documented in REGISTRY StackedDiD "Covariate balancing (CBWSDID)" Notes. | `stacked_did.py`, `balancing.py`, REGISTRY | follow-up | Low |
@@ -104,7 +105,7 @@ For survey-specific limitations (`NotImplementedError` paths), see the
 | `SpilloverDiD` estimator-level end-to-end vcov reconstruction tests (`bread @ meat @ bread` against `res.vcov`): requires exposing the estimator's internal `X_2_kept` design arrays; the surface is currently pinned from different angles (uniform-weight bit-identity, drift goldens, manual lincom reconstruction at rtol=1e-6). | `spillover.py`, `tests/test_spillover.py` | follow-up | Low |
 | `SpilloverDiD` Wave E.3 `finite_mask + design-subset` hygiene not yet adopted for TwoStageDiD's analogous pattern (`two_stage.py:567-601`) — separate parity follow-up noted in the `docs/api/spillover.rst` Restrictions block. | `two_stage.py` | Wave E.3 | Low |
 | `HeterogeneousAdoptionDiD` `covariates=` (Theorem 6 multivariate-covariate extension) not implemented — `fit(covariates=...)` raises `NotImplementedError` via the shipped future-work trap (locked by the `test_had.py` / `test_methodology_had.py` L73 tests); the deferred work is the Theorem 6 extension itself. | `had.py` | Phase 2a | Low |
-| MultiPeriodDiD wild bootstrap not supported (falls back to analytical, n_bootstrap-independent) — user-facing edge-case limitation; the 4.0 removal replaces the fallback with a raise (v4-design §4.1). | `estimators.py:1574` | — | Low |
+| MultiPeriodDiD wild bootstrap not supported (falls back to analytical, n_bootstrap-independent) — user-facing edge-case limitation; the 4.0 removal replaces the fallback with a raise (v4-design §4.1), and the merged TWFE event-study mode already RAISES since 3.9 (Phase 3(a)) — this row now governs only the deprecated class itself. | `estimators.py` (MultiPeriodDiD.fit wild-fallback block) | — | Low |
 | `predict()` raises `NotImplementedError` — rarely needed; user-facing limitation. | `estimators.py:890-911` | — | Low |
 
 ## Version-gated (v4)
@@ -126,6 +127,7 @@ decisions (refactor waivers, perf trade-offs, test-infrastructure calls) are rec
 
 | Decision | Location | Verified |
 |----------|----------|----------|
+| **MultiPeriodDiD deprecation shim loses static constructor-arg checking (3.9 window).** The M-010 shim is `__init__(*args, **kwargs)` + an import-time `__signature__` mirror of DiD's constructor: runtime introspection (get_params/set_params, `inspect.signature`) and eager validation are fully preserved, but static type checkers / IDEs cannot check constructor arguments for the deprecated class until its 4.0 removal. Accepted: the alternative (hand-mirroring ~20 parameters) is a drift magnet on a class with one minor version of remaining life. | `diff_diff/estimators.py` | 3(a) / 2026-08-07 |
 | **DCDH `sklearn.base.clone` param-identity failure won't-fix.** `ChaisemartinDHaultfoeuille._validate_paths_of_interest` unconditionally canonicalizes `paths_of_interest` into a fresh `List[Tuple[int, ...]]`, so sklearn `clone()`'s post-construction `param1 is param2` identity check fails for configured instances - a pre-existing normalization the BaseEstimator mixin PR documented rather than changed (get_params/set_params signatures are clone-compatible; the dependency-free `cls(**est.get_params())` config-equality contract is the enforced one, `tests/test_base_estimator.py`). Fixing would mean returning the caller's raw object from a validator whose job is canonicalization. | `chaisemartin_dhaultfoeuille.py` | mixin PR / 2026-08-01 |
 | **scikit-learn stays out of dev deps; clone-identity tests remain importorskip-only.** The sklearn-`clone()` round-trip tests (`test_base_estimator.py`, had/rdd/cic suites) run only where scikit-learn happens to be installed - deliberate, matching the numpy/pandas/scipy-only dependency posture; the always-running contract is the dependency-free re-instantiation config-equality test. | `tests/test_base_estimator.py` | mixin PR / 2026-08-01 |
 | **Plan-review hash gate threat model: accident prevention, NOT adversarial defense.** The ExitPlanMode content-hash gate (hook + `plan_snapshot.py`) exists to stop accidents — stale approvals, concurrent-worktree cross-talk, plans edited mid-review — all of which it closes by construction (snapshot identity + invocation-unique state tokens, 30+ behavioral tests). It does NOT and cannot defend against a malicious local process: nothing verifies review AUTHORSHIP, and such an actor can simply write a matching review file directly — no userland hook can prevent that short of signed reviews, which is out of scope for a personal workflow aid. Review findings that presuppose a hostile local actor against this gate are waived by this decision (2026-07-20, after 7 local AI-review rounds converged on ever-deeper adversarial-model refinements with no reachable fixpoint). Genuine accident vectors remain in scope and are fixed as found. | `.claude/hooks/check-plan-review.py`, `.claude/scripts/plan_snapshot.py` | 2026-07-20 |

diff --git a/README.md b/README.md
@@ -90,7 +90,7 @@ For rigorous DiD analysis, follow these 8 steps. Skipping diagnostic steps produ
 3. **Test parallel trends** - simple 2x2: `check_parallel_trends()`, `equivalence_test_trends()`; staggered: inspect CS event-study pre-period coefficients (generic PT tests are invalid for staggered designs). Insignificant pre-trends do NOT prove PT holds.
 4. **Choose estimator** - staggered adoption -> CS/SA/BJS (NOT plain TWFE); few treated units -> SDiD; factor confounding -> TROP; simple 2x2 -> DiD. Run `BaconDecomposition` to diagnose TWFE bias.
 5. **Estimate** - `estimator.fit(data, ...)`. Always print the cluster count first and choose inference method based on the result (cluster-robust if >= 50 clusters, wild bootstrap if fewer - for DifferenceInDifferences pass `cluster=`; TwoWayFixedEffects auto-clusters at unit level).
-6. **Sensitivity analysis** - `compute_honest_did(results)` for bounds under PT violations (MultiPeriodDiD, CS, or dCDH natively; a StackedDiD `results.aggregate('event_study')` container also admits - needs `kappa_pre >= 2`), `run_all_placebo_tests()` for 2x2 falsification, specification comparisons for staggered designs.
+6. **Sensitivity analysis** - `compute_honest_did(results)` for bounds under PT violations (MultiPeriodDiD, CS, or dCDH natively; the TwoWayFixedEffects `event_study=True` surface and a StackedDiD `results.aggregate('event_study')` container also admit - Stacked needs `kappa_pre >= 2`), `run_all_placebo_tests()` for 2x2 falsification, specification comparisons for staggered designs.
 7. **Heterogeneity** - CS: `results.aggregate('group')`/`'event_study'` (post-fit, no refit); SA: `results.event_study_effects` / `to_dataframe(level='cohort')`; Stacked: `results.aggregate('event_study')`/`'simple'` post-fit views (surface always computed since 3.9); EDiD: `results.aggregate(...)` post-fit from retained EIFs (3.9); ImputationDiD/TwoStageDiD: `results.aggregate(...)` post-fit from panel-backed kits (3.9); ContinuousDiD: `results.aggregate('dose'/'simple'/'event_study')` post-fit (3.9; dose/simple are views, event_study recomputes); subgroup re-estimation.
 8. **Robustness** - compare 2-3 estimators (CS vs SA vs BJS), report with and without covariates (shows whether conditioning drives identification), present pre-trends and sensitivity bounds.
 
@@ -100,7 +100,7 @@ Full guide: `diff_diff.get_llm_guide("practitioner")`.
 
 - [DifferenceInDifferences](https://diff-diff.readthedocs.io/en/stable/api/estimators.html) - basic 2x2 DiD with robust/cluster-robust SEs, wild bootstrap, formula interface, and fixed effects
 - [TwoWayFixedEffects](https://diff-diff.readthedocs.io/en/stable/api/estimators.html) - panel data DiD with unit and time fixed effects via within-transformation or dummies
-- [MultiPeriodDiD](https://diff-diff.readthedocs.io/en/stable/api/estimators.html) - event study design with period-specific treatment effects for dynamic analysis
+- [MultiPeriodDiD](https://diff-diff.readthedocs.io/en/stable/api/estimators.html) - event study design with period-specific treatment effects for dynamic analysis (deprecated 3.9 - use TwoWayFixedEffects `event_study=True`)
 - [CallawaySantAnna](https://diff-diff.readthedocs.io/en/stable/api/staggered.html) - Callaway & Sant'Anna (2021) group-time ATT estimator for staggered adoption
 - [ChaisemartinDHaultfoeuille](https://diff-diff.readthedocs.io/en/stable/api/chaisemartin_dhaultfoeuille.html) - de Chaisemartin & D'Haultfœuille (2020/2022) for **reversible (non-absorbing) treatments** with multi-horizon event study, normalized effects, cost-benefit delta, sup-t bands, and dynamic placebos. The most general option for treatments that switch on AND off (see also `LPDiD`/`TROP` `non_absorbing`). Alias `DCDH`.
 - [SunAbraham](https://diff-diff.readthedocs.io/en/stable/api/staggered.html) - Sun & Abraham (2021) interaction-weighted estimator for heterogeneity-robust event studies