docs: publish REGISTRY.md + REPORTING.md as in-site Sphinx pages (MyST)

[igerber]

Summary

• Renders docs/methodology/REGISTRY.md and REPORTING.md as in-site RTD pages (MyST) under a new Methodology toctree section, closing the TODO row: API-doc cross-refs now use :doc: links instead of off-site blob/main GitHub URLs, so stable-docs readers no longer land on a different revision than their installed version (docs/api/business_report.rst, diagnostic_report.rst converted; the two tutorial notebooks keep their functional GitHub links — editing executed notebooks for a link swap wasn't worth the re-execution churn).
• myst-parser>=2.0 added to all three synced dependency surfaces (pyproject docs extra, .readthedocs.yaml post_install, docs-tests.yml pip lines). All other repo-internal markdown under docs/ (performance notes — deliberately not on RTD per repo convention — paper reviews, roadmaps, tutorials README) is explicitly excluded from the Sphinx build, so nothing internal leaks onto RTD and no orphan warnings fire.
• The feared multi-round -W risk didn't materialize: the 4.5k-line REGISTRY renders clean with dollarmath/amsmath + myst_heading_anchors=4. The build surfaced three latent doc defects, now fixed: a ToC anchor typo (#differenceinifferences — broken on GitHub too), an H1→H3 heading-level jump, and the "Diagnostics & Sensitivity" heading retitled to "Diagnostics and Sensitivity" (GitHub slugs & as a double hyphen; docutils collapses consecutive hyphens in ids — no single anchor spelling can satisfy both, so the title now slugs identically everywhere). Repo-wide grep confirms no other references to the old anchor.
• Verified: clean local make -C docs html SPHINXOPTS="-W" — 0 warnings (same command as the docs-tests CI job).

Methodology references (required if estimator / math changes)

• Method name(s): N/A — documentation infrastructure only (REGISTRY content changes are the three rendering fixes above; no methodology text altered)
• Paper / source link(s): N/A
• Any intentional deviations from the source (and why): None

Validation

• Tests added/updated: None (docs build is CI-validated by the docs-tests.yml sphinx-build job under -W)
• Backtest / simulation / notebook evidence (if applicable): local 0-warning -W build log

Security / privacy

• Confirm no secrets/PII in this PR: Yes

---

Generated with Claude Code

[github-actions]

Overall Assessment

✅ Looks good. No unmitigated P0/P1 findings.

Executive Summary

• No estimator, math, weighting, variance/SE, identification, or default-behavior changes found.
• REGISTRY changes are rendering/anchor fixes only: ToC slug, heading rename, and heading-level correction.
• MyST wiring is consistently added across Sphinx config, RTD, pyproject docs extras, and docs CI.
• No new inference, NaN/Inf, control-group, empty-result, or parameter-propagation risks were introduced.
• P3 informational: two TODO.md performance rows should preserve the prior technical caveats more accurately.

Methodology

• Severity: None
  Impact: No methodology-affecting implementation changes. The edits in docs/methodology/REGISTRY.md:L10, docs/methodology/REGISTRY.md:L31, docs/methodology/REGISTRY.md:L3452, and docs/methodology/REGISTRY.md:L4962 only affect anchors/headings for documentation rendering.
  Concrete fix: None.

Code Quality

• Severity: None
  Impact: The PR changes documentation/build configuration only; no modified estimator code paths or inline inference computation were introduced.
  Concrete fix: None.

Performance

• Severity: P3 informational
  Impact: The new stratified survey-bootstrap TODO says draw-block tiling can reproduce the stream bit-identically, but the current stratified generator consumes RNG stratum-major: all draws for each stratum are generated before the next stratum, plus pooled singleton handling. A simple draw-block loop would interleave stratum draws and change the RNG stream. See TODO.md:L56, diff_diff/bootstrap_utils.py:L587-L635, and the current fallback contract in diff_diff/bootstrap_chunking.py:L141-L143.
  Concrete fix: Reword the TODO to say bit-identical stratified chunking would require explicit RNG state skipping/per-stratum streams or a documented stream-layout change with baseline recapture.

Maintainability

• Severity: P3 informational
  Impact: The SyntheticControl snapshot TODO now frames the retained snapshot only as avoidable memory, but the result snapshot is intentionally retained for post-fit diagnostics and excluded from pickle for size/privacy. See TODO.md:L52 and diff_diff/synthetic_control_results.py:L31-L37.
  Concrete fix: Preserve the caveat that releasing/lazily rebuilding the snapshot needs either an explicit release/opt-out API or a documented change to the post-fit diagnostic freeze contract.

Tech Debt

• Severity: P3 informational
  Impact: The TODO changes are tracked and deferrable; they do not create silent incorrect estimates. The risk is future implementation guidance losing important constraints.
  Concrete fix: Keep these rows, but restore the caveats noted above so future work does not accidentally break RNG parity or result-object diagnostic semantics.

Security

• Severity: None
  Impact: No suspicious secret/token patterns found in the changed files reviewed.
  Concrete fix: None.

Documentation/Tests

• Severity: None
  Impact: The docs publishing path is wired in docs/conf.py:L23-L42, docs/index.rst:L142-L148, pyproject.toml:L74-L85, .readthedocs.yaml:L13-L21, and .github/workflows/docs-tests.yml:L106-L118. I did not run the Sphinx build in this read-only review environment.
  Concrete fix: None; CI should validate make -C docs html SPHINXOPTS="-W".

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 63d7eeca69192f000426cccba285037cfd8ce97b

---

Overall Assessment

✅ Looks good. No unmitigated P0/P1 findings.

Executive Summary

• No estimator, variance/SE, weighting, identification, or default-behavior code paths changed.
• REGISTRY edits are documentation-rendering fixes only: anchor typo, heading rename, and heading-level correction.
• MyST docs wiring is consistently added across Sphinx config, RTD, pyproject docs extra, and docs CI.
• Prior P3 TODO concerns are resolved: the SyntheticControl snapshot and stratified bootstrap RNG caveats are now preserved.
• I could not run the Sphinx -W build locally because Sphinx is not installed in this read-only review environment.

Methodology

• Severity: None
  Impact: No methodology-affecting implementation changes. The changed REGISTRY lines only affect navigation/rendering: docs/methodology/REGISTRY.md:L10-L31, docs/methodology/REGISTRY.md:L3452-L3456, docs/methodology/REGISTRY.md:L4962-L4969.
  Concrete fix: None.

Code Quality

• Severity: None
  Impact: No modified estimator code, inference computation, NaN guards, control-group logic, or parameter propagation paths. Docs config changes are scoped and explicit in docs/conf.py:L23-L64.
  Concrete fix: None.

Performance

• Severity: None
  Impact: Prior stratified bootstrap TODO concern is addressed: TODO.md:L126 now records the stratum-major RNG stream and why bit-identical draw tiling is not a simple performance refactor.
  Concrete fix: None.

Maintainability

• Severity: None
  Impact: Prior SyntheticControl snapshot TODO concern is addressed: TODO.md:L125 now preserves the post-fit diagnostic freeze contract and pickle exclusion caveat.
  Concrete fix: None.

Tech Debt

• Severity: None
  Impact: The completed docs-publishing TODO row was removed from the actionable backlog, and the remaining tracked items stay properly classified.
  Concrete fix: None.

Security

• Severity: None
  Impact: No secrets or sensitive data introduced in the changed docs/config surfaces reviewed.
  Concrete fix: None.

Documentation/Tests

• Severity: None
  Impact: myst-parser is added consistently in pyproject.toml:L74-L85, .readthedocs.yaml:L13-L21, and .github/workflows/docs-tests.yml:L106-L118 / L143-L148; the Methodology toctree is added in docs/index.rst:L142-L148; API docs now use in-site :doc: links in docs/api/business_report.rst:L48-L66 and docs/api/diagnostic_report.rst:L14-L22.
  Concrete fix: None; CI should validate the claimed make -C docs html SPHINXOPTS="-W" build.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: d992d980a39e63c14fdd862f87a32557661b0268

---

Overall Assessment

✅ Looks good. No unmitigated P0/P1 findings.

Executive Summary

• No estimator, math, weighting, variance/SE, assumptions, or default behavior changed.
• REGISTRY edits are rendering/link fixes only: anchor typo, heading rename, and heading-level correction.
• MyST wiring is consistent across Sphinx config, RTD install, docs CI, and pyproject.toml.
• The completed TODO row was removed, while previously tracked deferred items remain preserved.
• I could not run the Sphinx -W build locally because Sphinx is not installed in this read-only review environment.

Methodology

• Severity: None
  Impact: No methodology-affecting implementation changes. The touched REGISTRY content is limited to navigation/rendering fixes at docs/methodology/REGISTRY.md:L9-L36, docs/methodology/REGISTRY.md:L3452-L3456, and docs/methodology/REGISTRY.md:L4963-L4974.
  Concrete fix: None.

Code Quality

• Severity: None
  Impact: No modified estimator code, inference computation, NaN handling, or parameter propagation paths. Docs config changes are scoped to MyST support and explicit Markdown exclusions in docs/conf.py:L23-L64.
  Concrete fix: None.

Performance

• Severity: None
  Impact: No runtime code paths changed. The prior stratified bootstrap RNG caveat remains tracked in TODO.md:L123.
  Concrete fix: None.

Maintainability

• Severity: None
  Impact: Dependency additions are kept in sync across pyproject.toml:L74-L85, .readthedocs.yaml:L13-L21, and .github/workflows/docs-tests.yml:L106-L148.
  Concrete fix: None.

Tech Debt

• Severity: None
  Impact: The completed docs-publishing TODO row was removed from the actionable backlog, and existing deferred/documented items remain tracked at TODO.md:L122-L126.
  Concrete fix: None.

Security

• Severity: None
  Impact: No secrets, credentials, or sensitive runtime surfaces introduced in the changed docs/config files.
  Concrete fix: None.

Documentation/Tests

• Severity: None
  Impact: Methodology pages are added to the Sphinx toctree at docs/index.rst:L142-L148; API docs now use in-site :doc: links at docs/api/business_report.rst:L48-L66 and docs/api/diagnostic_report.rst:L14-L22. The docs CI still builds with SPHINXOPTS="-W" at .github/workflows/docs-tests.yml:L114-L118.
  Concrete fix: None. CI should remain the source of truth for the claimed zero-warning Sphinx build since Sphinx is unavailable in this review container.