docs(v4): planning consolidation - alias diet + canonical 3.9 sequence (M-132..M-135, M-063 cancelled)

[igerber]

Summary

• Records the 2026-07-31 consolidation-scope decisions in the canonical pair (docs/v4-design.md + the CI-enforced docs/v4-deprecations.yaml): no staggered-family mega-merge, no ImputationDiD↔TwoStageDiD merge, and the moderate alias diet.
• Alias diet: CDiD, Stacked, Gardner deprecate at 3.9 and are removed at 4.0 (new ledger rows M-132..M-134, code_refs carrying the grep-verified reader surfaces); their 3.9 FutureWarning rides a module-level __getattr__ tracked by behavior row M-135 (introduced_in: "3.9", so the 3.9 cut cannot ship without it). EDiD was initially slated but is retained — the Chen–Sant'Anna–Xie paper brands its estimator EDiD throughout (Tables 6/7; docs/methodology/papers/chen-santanna-xie-2025-review.md records the same usage), which is the diet's own keep-the-literature-name criterion.
• The never-shipped Spillover alias introduction is cancelled: M-063 flips terminal (done + null new_target) as an anti-resurrection pin. Ledger row count 110 → 114 with matching test_v4_matrix.py constants; the ledger FORMAT CONTRACT's comment rule is qualified to line-leading-only (matching the scanner).
• docs/v4-design.md §9 is de-staled against the ledger: the phase-2 cell gains the shipped M-122..M-127 insertions, phase 3 gains M-064/M-082, the phase-5 roster is completed (M-020..M-027/M-064/M-084/M-086..M-089/M-117 re-listed; M-031 carved out — no 4.0 lifecycle work; M-016 moved to a property-window clause — its removal is 5.0) under an explicit citation semantic, and a new "Remaining 3.9 sequence" subsection becomes the single canonical statement of the remaining PR order.
• The TODO.md naming-guard row's phase-table agreement spec is amended from the unsatisfiable "and vice versa" to the enforceable two-direction form (with the parser rule and the version-derivation predicate stated). Duplicated flip-plan prose in DEFERRED.md and the REGISTRY M-010 note is trimmed to cross-links; .claude/memory.md 4.0-TARGET blocks compress to pointers; stale "scheduled for PR C" comments in tests/test_variance_conventions.py are updated to the converged post-M-127 reality.

Methodology references

• Method name(s): N/A — no estimator/math changes (planning, ledger, and documentation only; no runtime behavior changes).
• Paper / source link(s): Chen, Sant'Anna & Xie (2025) — cited for the EDiD naming evidence (docs/methodology/papers/chen-santanna-xie-2025-review.md).
• Any intentional deviations from the source (and why): None.

Validation

• Tests added/updated: tests/test_v4_matrix.py (ROW_COUNT_FLOOR 110 → 114, id-snapshot range (132, 135), alias-warning assertion message covers the surviving-target case); tests/test_variance_conventions.py (comment-only staleness fixes). Full matrix suite passes (238 passed, 17 skipped); test_variance_conventions.py collects cleanly; black/ruff clean on both.
• Backtest / simulation / notebook evidence (if applicable): N/A.

Security / privacy

• Confirm no secrets/PII in this PR: Yes

[github-actions]

Overall assessment: ✅ Looks good

Executive summary

• No estimator, math, weighting, variance, inference, assumption, or runtime-default changes.
• The CSX methodology review confirms the paper uses “EDiD” in Tables 6–7.
• Matrix/YAML validation found 114 unique lifecycle rows with consistent IDs.
• Two P2 planning issues remain; neither blocks approval.

Methodology

No findings. The alias changes affect naming only. The EDiD rationale matches docs/methodology/papers/chen-santanna-xie-2025-review.md:L177-L184 and docs/methodology/REGISTRY.md:L1334-L1336.

Code Quality

No findings.

Performance

No findings; no runtime code changed.

Maintainability

Incomplete alias reader inventory

• Severity: P2
• Location: docs/v4-deprecations.yaml:L1476-L1501
• Impact: The rows claim to inventory known reader surfaces, but M-133 omits diff_diff/guides/llms-autonomous.txt:L427,L985, while M-134 omits user-facing recommendations in diff_diff/practitioner.py:L416-L492 and diff_diff/business_report.py:L1681-L1687. A later removal following only code_refs could continue recommending retired aliases.
• Concrete fix: Add those files to the corresponding code_refs, or explicitly allowlist occurrences that are intended solely as method/author prose.

Tech Debt

Phase-table predicate excludes decision_due

• Severity: P2
• Location: TODO.md:L64
• Impact: The proposed guard accepts only introduced_in, deprecated_in, or removed_in. It would reject the legitimate phase-5 [M-008] citation because that env-default row is scheduled through decision_due: "4.0" (docs/v4-deprecations.yaml:L115-L126, docs/v4-design.md:L631).
• Concrete fix: Include decision_due for env-default rows and add a guard fixture covering M-008’s phase-5 citation.

Security

No findings.

Documentation/Tests

No additional findings. Static checks confirmed valid YAML, 114 unique IDs, clean diff whitespace, and valid Python syntax. Full pytest execution was unavailable because the review environment lacks project test dependencies.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 737886df9b0b5bdd6f54102a03ee0457f54f477e

---

Overall assessment: ✅ Looks good

Executive summary

• Both prior P2 findings are resolved.
• No estimator, weighting, variance, inference, assumptions, or defaults changed.
• EDiD retention matches the cited paper review and registry.
• Ledger validation found 114 unique rows with consistent phase citations.

Methodology

No findings. The EDiD rationale is supported by docs/methodology/papers/chen-santanna-xie-2025-review.md:L177-L184 and docs/methodology/REGISTRY.md:L1334-L1336.

Code Quality

No findings.

Performance

No findings; no runtime code changed.

Maintainability

No findings. M-133/M-134 now include the previously omitted reader surfaces at docs/v4-deprecations.yaml:L1476-L1501.

Tech Debt

Tracked naming-completeness guard

• Severity: P3 — informational
• Impact: Phase-table and consumer-coverage enforcement remains planned rather than implemented.
• Concrete fix: No action required for this PR; implement the tracked guard before Phase 2(c), as specified in TODO.md:L64.

The prior decision_due issue is resolved: env-default rows and M-008 are explicitly covered.

Security

No findings or apparent secrets.

Documentation/Tests

No findings. Static checks confirmed valid YAML, 114 unique IDs, existing nonterminal code_refs, valid Python syntax, and phase-table consistency. Full pytest execution was unavailable because the review image lacks pytest and NumPy.