docs(v4): 4.0 design spec + CI-enforced deprecation ledger (Phase 1)#697
Conversation
|
Overall Assessment ✅ Looks good. No unmitigated P0/P1 findings. Executive Summary
Methodology No P0/P1 findings.
Code Quality No findings. Performance No findings. Maintainability No findings. Tech Debt No separate findings. Security No findings. No secrets or credential material observed in the changed files. Documentation/Tests
|
037f2f3 to
8507736
Compare
|
🔁 AI review rerun (requested by @igerber) Head SHA: Overall Assessment ✅ Looks good. No unmitigated P0/P1 findings. Executive Summary
Methodology No P0/P1 findings.
Code Quality No findings. Performance No findings. Maintainability No findings. Tech Debt No separate findings. Security No findings. I did not observe secrets or credential material in the changed files. Documentation/Tests
|
|
🔁 AI review rerun (requested by @igerber) Head SHA: Overall Assessment ✅ Looks good. No unmitigated P0/P1 findings. Executive Summary
Methodology No P0/P1 findings.
Code Quality No findings. Performance No findings. The new matrix test is pure introspection and not on estimator hot paths. Maintainability No findings. Tech Debt No blocker findings. The v4 default flips and fastpath decision are now cross-linked from Security No findings. I did not observe secrets or credential material in the changed files. Documentation/Tests
Validation note: I could not run the test suite in this container because |
|
🔁 AI review rerun (requested by @igerber) Head SHA: Overall Assessment ✅ Looks good. No unmitigated P0/P1 findings. Executive Summary
Methodology
Code Quality No findings. Performance No findings. The new matrix enforcement is introspection/schema checking only and is not on estimator hot paths. Maintainability No findings. The immutable row-id snapshot, row-count floor, schema self-tests, and spec cross-reference checks improve ledger maintainability. Tech Debt No findings. Deferred 4.0 obligations are now tracked in the ledger and cross-linked from TODO where relevant. Security No findings. I did not observe secrets or credential material in the changed files. Documentation/Tests No findings. The previous Wooldridge Validation note: |
igerber
added
ready-for-ci
Normative design for the 4.0 program (docs/v4-design.md): three estimator
merges (TWFE absorbs MultiPeriodDiD with a unit-FE event-study default and
spec="pooled" compatibility, TripleDifference facade over the DDD pair, CiC
absorbs QDiD via method=), post-fit results.aggregate() with the unified
{simple, event_study, group, calendar} vocabulary, canonical results quintet
storage flip, library-wide param/column contract rules (post vs time,
first_treat, covariates, no _col suffixes), one inference surface, the
final alias table, and the 3.9-shim-then-4.0-enforce release sequencing
with the maint/3.8 patch-line rule.
Every deprecation lifecycle is a row in docs/v4-deprecations.yaml (71 rows:
the six locked design decisions expanded per-surface plus all five
pre-existing 4.0 obligations found by repo sweep, including the
df_convention default flip that carries no in-code warning; Wooldridge's
existing aggregate(type=)/summary(aggregation=) surfaces are covered by
dedicated value-migration rows). tests/test_v4_matrix.py asserts every
row's status against reality at HEAD: planned rows tripwire on new surface
appearing unflipped, shimmed/removed rows pin both sides plus
dedicated-test existence, param-value rows carry the full lifecycle with
test_ref-backed value enforcement, alias rows assert identity and __all__
membership, default-flip rows pin signature defaults, and the release gate
is two-sided (due rows must flip; early removals before the scheduled
version fail). Wired into docs-tests.yml so docs-only ledger/spec edits
cannot bypass enforcement. REGISTRY.md MultiPeriodDiD gains a labeled Note
reconciling the unit-FE parity target with the 3.x pooled default and the
scheduled 4.0 migration.
Docs + test only; no public API or numerical behavior change.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017eVKbBqzenDKa5idwtexQa
d287174 to
6e5dd83
Compare
|
🔁 AI review rerun (requested by @igerber) Head SHA: Overall Assessment ✅ Looks good. No unmitigated P0/P1 findings. Executive Summary
Methodology
Code Quality No findings. The matrix test keeps the parser/schema logic scoped and includes negative self-tests for schema drift. Performance No findings. The new enforcement is import/signature/schema introspection only and is not on estimator hot paths. Maintainability No findings. The immutable initial row snapshot, row-count floor, spec cross-reference check, and core status-vs-reality assertions make the ledger maintainable across later 4.0 PRs. Tech Debt No findings. Deferred default-flip and fastpath decisions are now tracked in the ledger and cross-linked from TODO. Security No findings. I did not observe secrets or credential material in the changed files. Documentation/Tests No findings. The previous M-086 Validation note: |
1 participant
Summary
docs/v4-design.md) every later 4.0-program PR is reviewed against - three estimator merges (TWFE absorbs MultiPeriodDiD with a unit-FE event-study default andspec="pooled"compatibility; TripleDifference becomes a facade over the 2x2x2 and staggered DDD engines; ChangesInChanges absorbs QDiD viamethod=), post-fitresults.aggregate()with the unified{simple, event_study, group, calendar}vocabulary, the canonical results-quintet storage flip, library-wide param/column contract rules, one inference surface, the final alias table, and the 3.9-shim-then-4.0-enforce release sequencing with the maint/3.8 patch-line rule.docs/v4-deprecations.yaml, 69 rows): every queued deprecation - the six locked design decisions expanded per-surface plus all five pre-existing 4.0 obligations found by repo sweep (including thedf_conventiondefault flip, which carries no in-code warning and would be invisible to a warnings-grep at cut time).tests/test_v4_matrix.py): asserts every ledger row's status against reality at HEAD - planned rows tripwire when new surface ships unflipped, shimmed/removed rows pin both sides plus dedicated-test existence, alias rows assert identity and__all__membership, default-flip rows pin signature defaults, and the release gate is two-sided (due rows must flip at the scheduled version; early removals before it fail). Committed scanner self-tests with negative fixtures for every schema rule. Wired intodocs-tests.yml(doc-snippets job + paths) so docs-only ledger/spec edits cannot bypass enforcement; also runs in the main test matrix.docs/conf.pyexclusion (internal doc, Sphinx-Wsafe), REGISTRY.md MultiPeriodDiD labeled Note reconciling the unit-FE parity target with the 3.x pooled default and the scheduled 4.0 migration, ROADMAP pointer, CHANGELOG[Unreleased], CLAUDE.md reference row, TODO.md lifecycle pointers,.claude/memory.mdcurrent-vs-target API conventions.Forward-reference note for review:
newlocators onplannedledger rows intentionally name 3.9/4.0 surface that does NOT exist at HEAD -tests/test_v4_matrix.pyasserts their ABSENCE until the owning phase ships. Nothing here is an undocumented deviation; this document set is the documentation.Methodology references (required if estimator / math changes)
docs/methodology/REGISTRY.mdgains a documentation-only labeled Note in the MultiPeriodDiD section (unit-FE target vs 3.x pooled default vs scheduled 4.0 migration).Validation
tests/test_v4_matrix.py(new; 158 checks green at HEAD, sub-0.1s, pure introspection, backend-neutral; module-level skip for installed-package CI runs, mirroringtest_doc_deps_integrity.py). Workflow contract suite (tests/test_openai_review.py -m '', 254 checks) green after thedocs-tests.ymledit.-Wbuild green with the new internal doc excluded.Security / privacy
🤖 Generated with Claude Code
https://claude.ai/code/session_017eVKbBqzenDKa5idwtexQa