ci(review): credit deferred rows in TODO.md OR DEFERRED.md (tracking-split prep 1/3)

[igerber]

Summary

• Update the AI-review contract so tracked-limitation crediting recognizes rows in EITHER TODO.md (Actionable Backlog) or the upcoming DEFERRED.md deferral/decision registry - prep for splitting the current TODO.md into an actionable-only backlog and a separate deferral registry.
• pr_review.md: "Deferred Work Acceptance" and the Assessment Criteria mitigation clauses now use file-level crediting (correct both before and after the split lands, so no transitional wording is needed).
• openai_review.py: the two _SUBSTITUTIONS TODO-phrase pairs updated in lockstep with the prompt (locked by test_all_substitutions_apply_to_real_prompt).
• ai_pr_review.yml: comment-only updates (the BASE_SHA staging note now also names DEFERRED.md); no mechanism change - the prompt is still staged from base, tracking files still read from the PR head.

The contract must land before the file-split PR because the workflow stages the review prompt from BASE_SHA (a PR cannot change its own review rules).

Methodology references (required if estimator / math changes)

• Method name(s): N/A - no methodology changes
• Paper / source link(s): N/A
• Any intentional deviations from the source (and why): None

Validation

• Tests added/updated: No test changes. Gate run: pytest tests/test_openai_review.py -m '' (full, incl. slow marks) - 254 passed, covering the substitution-lockstep and workflow-contract pins against the edited prompt.
• Backtest / simulation / notebook evidence (if applicable): N/A

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, math, weighting, variance/SE, assumptions, or defaults are changed.
• The DEFERRED.md crediting language is consistently added to the review prompt and local prompt substitutions.
• Workflow edits are comment-only and do not change checkout, prompt staging, or execution behavior.
• DEFERRED.md is not present yet, but the prompt still credits rows in either TODO.md or DEFERRED.md, so the transition is not blocking.
• Targeted test could not be run here because pytest is unavailable.

Methodology

No findings.

Severity: N/A
Impact: No causal inference methodology is affected by changes to .github/codex/prompts/pr_review.md, .claude/scripts/openai_review.py, or .github/workflows/ai_pr_review.yml.
Concrete fix: None required.

Code Quality

No findings.

Severity: N/A
Impact: The substitution strings in .claude/scripts/openai_review.py:L946-L955 match the updated prompt text in .github/codex/prompts/pr_review.md:L66-L105.
Concrete fix: None required.

Performance

No findings.

Severity: N/A
Impact: No runtime logic or model prompt assembly mechanics are changed.
Concrete fix: None required.

Maintainability

No findings.

Severity: N/A
Impact: The workflow comments at .github/workflows/ai_pr_review.yml:L116-L117 and .github/workflows/ai_pr_review.yml:L250-L258 clarify the intended future tracking split without changing behavior.
Concrete fix: None required.

Tech Debt

No findings.

Severity: N/A
Impact: The prompt now treats tracked rows in either TODO.md or DEFERRED.md as mitigation sources at .github/codex/prompts/pr_review.md:L59-L112, which is consistent with the planned split.
Concrete fix: None required.

Security

No findings.

Severity: N/A
Impact: The PR does not modify execution paths, credentials handling, checkout trust boundaries, or sandbox settings.
Concrete fix: None required.

Documentation/Tests

No blocking findings.

Severity: P3 informational
Impact: I attempted to run tests/test_openai_review.py::TestAdaptReviewCriteria::test_all_substitutions_apply_to_real_prompt, but pytest is not installed in this environment. The changed code is covered by the existing lockstep test in principle.
Concrete fix: None required for approval.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 4cbc54442b4e53683c8f66c33d2a16e691272560

---

Overall Assessment

✅ Looks good. No unmitigated P0/P1 findings.

Executive Summary

• No estimator, mathematical, inference, or default behavior changes.
• Both prompt substitutions match the revised review contract.
• Workflow changes are comments only.
• All 10 substitutions matched the real prompt in a structural check.
• No prior P0/P1 findings required remediation.

Methodology

Severity: N/A
Impact: No causal-inference methodology is affected.
Concrete fix: None.

Code Quality

Severity: N/A
Impact: Substitution wording remains synchronized with the prompt at .claude/scripts/openai_review.py:L941-L950.
Concrete fix: None.

Performance

Severity: N/A
Impact: No executable workflow or runtime behavior changed.
Concrete fix: None.

Maintainability

Severity: N/A
Impact: Workflow comments clearly describe the transitional TODO.md/DEFERRED.md arrangement at .github/workflows/ai_pr_review.yml:L116-L117 and L250-L258.
Concrete fix: None.

Tech Debt

Severity: N/A
Impact: The mitigation rules consistently recognize rows in either tracking file at .github/codex/prompts/pr_review.md:L57-L112. The temporary absence of DEFERRED.md does not prevent existing TODO.md entries from receiving credit.
Concrete fix: None.

Security

Severity: N/A
Impact: No execution paths, trust boundaries, credentials, or sanitization logic changed.
Concrete fix: None.

Documentation/Tests

Severity: P3 — informational
Impact: The existing lockstep test covers these substitutions. pytest was unavailable in this environment, but a dependency-free structural check confirmed all 10 substitutions match the real prompt and produce both new local-review phrases.
Concrete fix: None required.