docs(cs): keep cluster= (not deprecate) + close TODO row

[igerber]

Summary

• Resolves the backlog item "decide whether to formally deprecate CallawaySantAnna.cluster=X in favor of survey_design=SurveyDesign(psu=X)" with a decision to keep cluster= (do not deprecate), and removes the TODO.md row.
• Records the rationale in REGISTRY.md's CallawaySantAnna cluster-wiring section: cluster= is the canonical ergonomic single-level clustering kwarg (matches R fixest::feols(cluster=~unit), Stata vce(cluster id), statsmodels cov_type="cluster"), retained across all IF-based estimators (CS / EfficientDiD / ImputationDiD / TwoStageDiD). The cluster= → SurveyDesign(psu=cluster) synthesis is an internal implementation detail, not user-facing redundancy; survey_design= is the advanced entry point (strata / FPC / replicate weights) while bare cluster= is the common-case shorthand. Mirrors the HAD survey-API consolidation, which deprecated only the redundant survey= / weights= entry points and deliberately kept cluster=.

Methodology references

• Method name(s): CallawaySantAnna cluster-robust inference (API-surface decision, not a math change)
• Paper / source link(s): N/A — records a library API-design decision; no estimand or variance-formula change
• Any intentional deviations from the source (and why): None. Documents that cluster= is intentionally retained as the ergonomic kwarg (verified: no cluster= DeprecationWarning exists anywhere; cluster= is present on all four IF-based estimators).

Validation

• Tests added/updated: No test changes — docs-only (REGISTRY.md note + TODO.md row removal); no source or behavior change.
• Backtest / simulation / notebook evidence (if applicable): N/A

Security / privacy

• Confirm no secrets/PII in this PR: Yes

---

🤖 Generated with Claude Code

[github-actions]

Overall Assessment: ✅ Looks Good

Executive Summary

• Docs-only PR: no estimator, weighting, variance/SE, or default behavior changes.
• Affected surface is CallawaySantAnna.cluster= documentation, with sibling IF-based estimators referenced for API consistency.
• The new registry note is explicitly labeled as an API decision and documents retaining cluster=, so it resolves the removed TODO.md row cleanly.
• I found no unmitigated P0/P1 methodology, inference, edge-case, or security issues.
• No tests are required for this docs-only change.

Methodology

Finding: P3 informational — API decision documented, no action required

• Impact: The PR records that cluster= remains the canonical ergonomic single-level clustering kwarg rather than being deprecated in favor of survey_design=SurveyDesign(psu=...). This is an API-surface decision, not a methodology/math change.
• Evidence: The new note is explicitly labeled Note (API decision — cluster= retained, NOT deprecated) in docs/methodology/REGISTRY.md:L477. The surrounding CallawaySantAnna registry already documents the actual cluster/survey precedence and PSU synthesis behavior at docs/methodology/REGISTRY.md:L466-L475.
• Cross-check: The relevant estimator docstrings/signatures still expose cluster= without deprecation: diff_diff/staggered.py:L296-L305, diff_diff/efficient_did.py:L231-L245, diff_diff/imputation.py:L94-L103, diff_diff/two_stage.py:L1236-L1268.
• Concrete fix: None.

Code Quality

No findings. The PR only edits TODO.md and docs/methodology/REGISTRY.md; no executable code changed.

Performance

No findings. No runtime path changed.

Maintainability

No findings. Removing the actionable backlog row is consistent with adding the registry decision note that closes it: TODO.md:L31-L36, docs/methodology/REGISTRY.md:L477.

Tech Debt

No findings. The previously deferred decision is now documented as resolved rather than left untracked.

Security

No findings. The diff contains only methodology/TODO prose and no secrets or sensitive data.

Documentation/Tests

No findings. Documentation was updated in the methodology registry, and tests are not necessary for this docs-only API-decision record.