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

.claude/commands/dev-checklists.md

@@ -51,8 +51,10 @@ When implementing or modifying code that affects statistical methodology (estima
          (see CLAUDE.md "Documenting Deviations" for full format reference)
    - [ ] Include rationale (e.g., "defensive enhancement", "R errors here")
    - [ ] Ensure the deviation is an improvement, not a bug
-   - [ ] If deferring P2/P3 work: add row to `TODO.md` table under "Tech Debt from Code
-         Reviews" with columns `Issue | Location | PR | Priority`
+   - [ ] If deferring P2/P3 work: shippable items get a row in `TODO.md` (Actionable
+         Backlog; columns `Issue | Location | Origin | Effort | Priority`); blocked
+         items get a row in `DEFERRED.md` under the matching blocker section (columns
+         `Issue | Location | PR | Priority`) — see CLAUDE.md "Tracking-file map"
 
 4. **Testing methodology-aligned behavior**:
    - [ ] Test that edge cases produce documented behavior (NaN, warning, etc.)

.github/workflows/ai_pr_review.yml

@@ -113,8 +113,8 @@ jobs:
       # the `dismissed_comment` field on alert #14. The guard test
       # is belt-and-suspenders for accidental regressions, not a
       # complete adversarial parser.
-      # See DEFERRED.md (deferral registry; TODO.md until the split
-      # lands) for the long-term tracking of this gap.
+      # See DEFERRED.md (deferral registry) for the long-term
+      # tracking of this gap.
       # ─────────────────────────────────────────────────────────────────
       - name: Resolve PR number + metadata
         id: pr

CHANGELOG.md

@@ -8,6 +8,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Changed
+- **Internal tracking docs reorganized (no library behavior change).** `TODO.md` is now
+  the actionable backlog only; blocked / parked work and won't-fix decisions moved to the
+  new root-level `DEFERRED.md` (deferral & decision registry, same blocker sections plus
+  a decision record); monitoring and current-state notes (module-size watch, SE / typing
+  posture, the Apple-Silicon M4 BLAS note) moved to the repo-internal
+  `docs/dev-status.md`. Version-gated v4 lifecycle items are canonically tracked in
+  `docs/v4-deprecations.yaml` (the former "Deprecated Code" section is folded into ledger
+  ids M-001/M-002). The AI-review contract credits tracked rows in either `TODO.md` or
+  `DEFERRED.md` (landed ahead of this split in #698); ~55 cross-references in source
+  docstrings, error messages, REGISTRY.md, and docs were repointed. Two previously
+  untracked follow-ups referenced by docs now have registry rows (SpilloverDiD Wave E.3
+  `finite_mask` parity; HAD `covariates=` kwarg-trap).
 - **Documentation site restructured around 5 top-level sections** (Getting Started /
   Practitioner Guide / Tutorials / User Guide / API Reference). The previous flat
   navigation put 40 pages into the pydata-sphinx-theme header, leaving most of the

CLAUDE.md

@@ -116,25 +116,38 @@ wording will cause a P1 finding ("undocumented methodology deviation").
 | `- **Deviation from R:** <text>` | Intentional differences from R packages | `- **Deviation from R:** R's fixest uses t-distribution at all levels` |
 | `**Note (deviation from R):** <text>` | Combined form, inline within edge case bullets | See SyntheticDiD section in REGISTRY.md |
 
-**TODO.md format** — for deferring P2/P3 items only (P0/P1 cannot be deferred):
-
-Add a row to `TODO.md`. If the item is genuinely shippable (clear path, no external
-blocker), put it under **Actionable Backlog** in the appropriate sub-section
-(`Methodology / correctness`, `Performance`, or `Testing / docs`). If it is blocked, put it
-under **Deferred / Documented** in the matching blocker sub-section (`Paper-gated / needs
-methodology derivation`, `Needs external reference (R / Stata / Julia)`, `Parked — pending
-user demand / out of scope`, or `Won't-fix / waived`). Either way the AI reviewer's
-deviation-grep resolves on the row's `Location` + reason text. The two buckets use
-different table shapes — Actionable rows carry an `Effort` column, Deferred rows a `PR`
-column:
-
-Actionable Backlog:
+**Tracking-file map** — for deferring P2/P3 items only (P0/P1 cannot be deferred):
+
+- **Shippable** (clear path, no external blocker) → a row in `TODO.md` under
+  **Actionable Backlog**, in the matching sub-section (`Methodology / correctness`,
+  `Performance`, or `Testing / docs`).
+- **Blocked** → a row in `DEFERRED.md` under the matching blocker section
+  (`Paper-gated / needs methodology derivation`, `Needs external reference
+  (R / Stata / Julia)`, `Parked — pending user demand / out of scope`, or
+  `Version-gated (v4)`).
+- **Decisions** (won't-fix / waived): if the decision pins **user-visible behavior or
+  methodology**, record it as a REGISTRY.md Note using the labels above; if it is
+  **internal engineering** (refactor waiver, perf trade-off, test-infrastructure call),
+  add it to `DEFERRED.md` → **Decision record — won't-fix / waived**.
+- **Version-gated lifecycle items** (deprecated-kwarg removals, v4 default flips):
+  `docs/v4-deprecations.yaml` (CI-enforced) is the lifecycle authority — never restate
+  ledger status/targets in a row. A row carrying real implementation work (e.g. a soak
+  or recapture protocol) may exist in TODO.md/DEFERRED.md but must cross-link its
+  `M-xxx` id.
+- **Monitoring / current-state notes** (module sizes, tooling posture, platform quirks)
+  go in `docs/dev-status.md`, not a backlog row.
+
+The AI reviewer's deviation-grep resolves on a row's `Location` + reason text in EITHER
+`TODO.md` or `DEFERRED.md`. The two files use different table shapes — Actionable rows
+carry an `Effort` column, DEFERRED rows a `PR` column:
+
+TODO.md → Actionable Backlog:
 
 | Issue | Location | Origin | Effort | Priority |
 |-------|----------|--------|--------|----------|
 | Description of the work item | `file.py` | #NNN | Quick/Mid/Heavy | Medium/Low |
 
-Deferred / Documented:
+DEFERRED.md (blocker sections):
 
 | Issue | Location | PR | Priority |
 |-------|----------|----|----------|