docs(dml): Chang (2020) published-version + replication-code cross-check

[igerber]

Summary

• Record the Chang (2020) published-version cross-check (doi:10.1093/ectj/utaa001, printed article pp. 177-191 + printed Appendix A), resolving the DEFERRED "published-version cross-check" row and confirming the Case 3 blocker in the version of record.
• Per-item verdicts appended to the review's suspected-typo list: every typo checkable from print persists unchanged (the p̂_k/λ̂_k normalizer in Definition 3.1(b), the Σ_20 ψ_1 term, the multilevel D_i/λ_0, both Lasso-penalty-recipe issues); Theorem proofs and the RCS/multilevel simulations are online-supplement-only, so three items remain uncheckable from print. New K=2 qualification: the printed normalizer is invalid only for K > 2 (at K = 2 it is exactly the auxiliary-sample mean).
• The author's replication code (github.com/NengChiehChang/Diff-in-Diff, pinned commit e93773d1c5ed, linked from published footnote 1) was inspected: it hard-codes k = 2 and uses MIXED conventions — p̂_k = propensity-trimmed evaluation-fold mean, λ̂_k = auxiliary-sample mean — plus fixed-threshold row-dropping and an RCS realized-score-dependent deletion, so it is recorded as an equation-level reference only, never a numerical oracle. The library's DoubleML-anchored global-share convention stands (documented deviation, now from the author's code as well as the printed algorithm).
• Published empirical Table 2 numbers recorded (they DIFFER from the arXiv Table 1 — results were re-run for publication); the published set is any future replication target.
• Bookkeeping: REGISTRY p̂ convention Note updated; both "R: none" reference-inventory lines replaced with the pinned author code; DEFERRED cross-check row retired, Case 3 row amended (blocker confirmed, kept).

Methodology references (required if estimator / math changes)

• Method name(s): N/A — no estimator or math changes (documentation-only cross-check record)
• Paper / source link(s): Chang, N.-C. (2020), The Econometrics Journal 23(2), 177-191, https://doi.org/10.1093/ectj/utaa001; author replication code github.com/NengChiehChang/Diff-in-Diff @ e93773d1c5ed
• Any intentional deviations from the source (and why): None new — the existing documented p̂ = mean(D) global-share deviation is re-affirmed with the published text and author code as additional evidence

Validation

• Tests added/updated: No test changes (docs-only). changelog_compile.py check green; CHANGELOG Unreleased stays pointer-only.
• Backtest / simulation / notebook evidence (if applicable): claims verified directly against the published PDF and the pinned GitHub commit (file/line citations in the review doc).

Security / privacy

• Confirm no secrets/PII in this PR: Yes

Changelog

• changelog.d/ fragment added (or N/A - no user-visible change): N/A - no user-visible change (methodology documentation and backlog records only)

[github-actions]

Overall Assessment

✅ Looks good — no P0/P1 findings. The PR is documentation-only; P2 wording inconsistencies do not affect estimator behavior.

Executive Summary

• No estimator, weighting, variance, assumptions, defaults, or inference code changed.
• The global p̂ convention remains a documented deviation and is not a defect.
• Two passages overstate or contradict the scope of the published-version verification.
• The reported Table 2 percentage does not match the recorded coefficients.
• Case 3 remains properly tracked in DEFERRED.md; no changelog fragment is required.

Methodology

Finding M1 — Published proof verification is overstated

• Severity: P2
• Location: docs/methodology/REGISTRY.md:L794-L797; docs/methodology/papers/chang-2020-review.md:L269
• Impact: The Registry says the “algorithm-vs-proof contradiction survives peer review unchanged,” while the review acknowledges that the published proofs are supplement-only and were not checked. Only the published algorithmic formula was verified.
• Concrete fix: Say that the published formula persists and remains inconsistent with the arXiv-v3 proof, or inspect and cite the published online-supplement proof before claiming the complete contradiction survived unchanged.

Finding M2 — K=2 qualification contradicts the preceding description

• Severity: P2
• Location: docs/methodology/papers/chang-2020-review.md:L267-L269
• Impact: Line 267 calls (1/n)Σ_{I_k^c} invalid “as printed” without qualification, while the new text correctly explains that it is a valid auxiliary-sample mean when K=2.
• Concrete fix: Qualify line 267 with “for K>2; at K=2, |I_k^c|=n.”

Documented deviation

• Severity: P3 informational
• Location: docs/methodology/REGISTRY.md:L780-L818
• Impact: The library’s global full-sample p̂ differs from the printed algorithm and author code, but it is explicitly labeled as a documented deviation and anchored to DoubleML parity.
• Concrete fix: None required.

Code Quality

No findings; executable code is unchanged.

Performance

No findings; the PR introduces no runtime path.

Maintainability

No findings beyond the methodology wording corrections above.

Tech Debt

• Severity: P3 informational
• Impact: The unresolved Case 3 derivation, overlap conditions, and variance theorem remain tracked in DEFERRED.md:L23.
• Concrete fix: None required in this PR.

Security

No findings; no secrets, credentials, or executable dependencies were added.

Documentation/Tests

Finding D1 — Recorded percentage conflicts with Table 2 values

• Severity: P2
• Location: docs/methodology/papers/chang-2020-review.md:L281
• Impact: |-5.222| is approximately 78.3% above |-2.928|, not approximately 60%. Readers cannot tell whether 60% is a source quotation or a calculation.
• Concrete fix: Replace it with 78%, or explicitly state that the published narrative says 60% despite Table 2 implying 78%.

No tests are needed for this documentation-only change. The changelog-fragment check passes, and no fragment is owed.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: a84af5bbb6c40c06a795939c11051d3ede20cd5d

---

Overall Assessment

✅ Looks good — no unmitigated P0/P1 findings.

Executive Summary

• All three previous P2 findings are resolved.
• Published-proof claims are now correctly scoped to printed material.
• The K=2 normalizer qualification and Table 2 arithmetic discrepancy are explicit.
• No estimator, inference, variance, or default behavior changed.
• The changelog-fragment check passes; no fragment is required.

Methodology

Documented global-share deviation

• Severity: P3 informational
• Location: docs/methodology/REGISTRY.md:L780-L820
• Impact: The library’s global p̂ convention differs from the paper and author code, but the deviation and its DoubleML justification are clearly documented.
• Concrete fix: None required.

The prior proof-scope and K=2 findings are resolved at docs/methodology/REGISTRY.md:L793-L807 and docs/methodology/papers/chang-2020-review.md:L267-L270.

Code Quality

No findings; executable code is unchanged.

Performance

No findings; no runtime path changed.

Maintainability

No findings.

Tech Debt

Deferred Case 3 derivation

• Severity: P3 informational
• Location: DEFERRED.md:L23
• Impact: Missing Case 3 assumptions and variance derivation remain explicitly tracked.
• Concrete fix: None required in this PR.

Security

No findings; no executable dependencies, credentials, or secrets were added.

Documentation/Tests

The prior Table 2 percentage finding is resolved at docs/methodology/papers/chang-2020-review.md:L281, which now distinguishes the paper’s 60% statement from the approximately 78% arithmetic result.

No tests or changelog fragment are required for this documentation-only change.