docs: split tracking into TODO.md (actionable) / DEFERRED.md (registry) / docs/dev-status.md (split 2/3)

[igerber]

Summary

• Restructures the internal tracking docs (no library behavior change): TODO.md becomes the actionable backlog only (9 rows, priority-ordered); DEFERRED.md (a git mv of the old TODO.md, kept as its own commit so blame follows the bulk) becomes the deferral & decision registry (Paper-gated 15 / Needs-external-reference 18 / Parked 36 / Version-gated 1 / Decision record 8); monitoring and current-state notes move to the repo-internal docs/dev-status.md (added to conf.py exclude_patterns for the -W build; module table refreshed with 5 newer modules and current line counts).
• Pointer sweep (~70 sites) across source docstrings, runtime rejection messages, REGISTRY.md, METHODOLOGY_REVIEW.md, performance docs, API RST, paper reviews, tutorial notebooks, and the v4 ledger notes - covering four distinct stale phrasings ("TODO.md", bare "tracked in TODO", "TODO row NN", "TODO Deferred -> Parked"). The triple_diff conley rejection message and its match="TODO" test pin are updated as a pair.
• Convention updates: CLAUDE.md gains a tracking-file map plus the new decisions rule (behavioral decisions -> REGISTRY.md Notes; internal-engineering decisions -> DEFERRED.md Decision record; docs/v4-deprecations.yaml stays the lifecycle authority with M-xxx cross-links); dev-checklists' stale "Tech Debt from Code Reviews" pointer fixed. The old "Deprecated Code" section is superseded by ledger ids M-001/M-002.
• Correctness fixes folded in: unstaled the "joint-Stute deferred" claim (shipped via stute_joint_pretest); four doc-referenced follow-ups that had no tracking row now have rows (SpilloverDiD finite_mask parity / covariates= scope cut / vcov-reconstruction tests; HAD Theorem-6 covariates); the MPD weighted-CR2-BM REGISTRY note rewritten to the verified survey-variance precedence contract (needs_survey_vcov is unconditionally True; MultiPeriodDiD.fit() exposes survey_design=, not bare weights=); two investigated-and-parked rows moved out of Paper-gated.
• Row integrity: all 131 moved table rows are byte-identical to the pre-split file (verified mechanically); the only exceptions are the two reshaped Known-Limitations rows and the practitioner.py line-count refresh.
• Follows ci(review): credit deferred rows in TODO.md OR DEFERRED.md (tracking-split prep 1/3) #698 (contract prep): the reviewer credits tracked rows in either file, so this PR also removes ci(review): credit deferred rows in TODO.md OR DEFERRED.md (tracking-split prep 1/3) #698's transitional comment wording.

Known residual (deliberate): the DIFF_DIFF_SOLVE_OLS_FASTPATH and df_convention rows keep their implementation-work detail alongside M-xxx cross-links - per the CLAUDE.md rule codified here, the ledger owns lifecycle state while rows own execution work. A tracking-contract guard test enforcing this division is filed as an actionable TODO.md row.

Merge-strategy note: this PR is intentionally two commits (pure rename + restructure). Squash-merging collapses them, so git log --follow DEFERRED.md won't pair the rename (recoverable via git blame -C -C); "Rebase and merge" preserves the rename natively. Maintainer's choice.

Methodology references (required if estimator / math changes)

• Method name(s): N/A - no methodology changes (estimator files receive docstring/comment/error-message pointer updates only; the REGISTRY MPD note correction documents existing behavior, verified against estimators.py/survey.py/linalg.py)
• Paper / source link(s): N/A
• Any intentional deviations from the source (and why): None

Validation

• Tests added/updated: tests/test_triple_diff.py (conley-rejection pointer pin updated with its message; test renamed ..._deferred_pointer); docstring-only updates in 8 other test files. Runs: targeted suites over every touched estimator surface (triple_diff/spillover/stacked/wooldridge/imputation/two_stage/efficient_did/had conley-vcov-trends paths - 400+ tests), pytest tests/test_openai_review.py -m '' (264 passed), collection checks on all docstring-edited test files, mypy diff_diff (zero), black/ruff on touched files, make -C docs html SPHINXOPTS="-W" (green - dev-status.md excluded like the other repo-internal docs), and a mechanical row-integrity check (131/131 moved rows byte-identical).
• Backtest / simulation / notebook evidence (if applicable): notebooks 23/27 received JSON-comment pointer edits only (validated JSON; not re-executed - outputs unchanged).

Security / privacy

• Confirm no secrets/PII in this PR: Yes

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01H8PDhdrdQH2DM8yAeEnib7

[github-actions]

Overall assessment

✅ Looks good — no unmitigated P0/P1 findings.

Executive summary

• No estimator, weighting, variance, identification, or default behavior changed.
• The MultiPeriodDiD survey-variance clarification matches implementation.
• Tracking-row counts match the stated split.
• One non-blocking stale TODO cross-reference remains.
• No performance or security concerns.

Methodology

• Severity: P3 — Informational
  • Impact: The MPD clarification correctly states that survey TSL/replicate variance takes precedence over CR2-BM. This matches needs_survey_vcov=True and the MPD gating logic.
  • Concrete fix: None.
  • Locations: docs/methodology/REGISTRY.md:L256-L262, diff_diff/survey.py:L726-L728, diff_diff/estimators.py:L1897-L1899

Code Quality

No findings. Modified Python code contains pointer/message changes only.

Performance

No findings. No executable performance paths changed.

Maintainability

No additional findings. The planned tracking-contract guard is appropriately tracked in TODO.md:L46.

Tech Debt

• Severity: P3 — Informational
  • Impact: Deferred work remains explicitly tracked. Counts match 15 paper-gated, 18 external-reference, 36 parked, 1 version-gated, 8 decisions, and 9 actionable rows.
  • Concrete fix: None.

Security

No findings. The workflow change is comment-only and introduces no execution or permission changes.

Documentation/Tests

• Severity: P2 — Stale tracking reference
  • Impact: The survey methodology note and regression-test diagnostics still direct readers to the removed TODO § "Won't-fix / waived" section.
  • Concrete fix: Replace these references with DEFERRED.md § "Decision record — won't-fix / waived".
  • Locations: docs/methodology/REGISTRY.md:L5679-L5681, tests/test_survey.py:L2155-L2158, tests/test_survey.py:L2249-L2253

Test execution was unavailable because pytest is not installed in the review environment.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: f8d2bfb70f2986953c44ddd9fe7f4ce51f7bb058

---

Overall assessment

✅ Looks good — no unmitigated P0/P1 findings.

Executive summary

• Prior stale TODO references are corrected.
• No estimator, weighting, variance, identification, or default behavior changed.
• MPD survey-variance clarification matches implementation.
• Tracking row counts and refreshed module sizes reconcile.
• No security or performance concerns.

Methodology

• Severity: P3 — Informational
  • Impact: The MPD clarification correctly documents that survey TSL/replicate variance supersedes CR2-BM.
  • Concrete fix: None.
  • Locations: docs/methodology/REGISTRY.md:L244-L263, diff_diff/survey.py:L726-L728, diff_diff/estimators.py:L1897-L1899

Code Quality

No findings. Modified Python behavior is limited to pointer/error-message text.

Performance

No findings.

Maintainability

No findings. The tracking split has clear ownership rules and matching cross-references.

Tech Debt

No findings. Counts reconcile to 9 actionable rows and deferred sections of 15/18/36/1/8 rows.

Security

No findings. The workflow modification is comment-only.

Documentation/Tests

No findings. The previous P2 is resolved at docs/methodology/REGISTRY.md:L5679-L5681 and tests/test_survey.py:L2155-L2158,L2249-L2253.

git diff --check passed. Tests were not run because pytest is unavailable in the review environment.