docs: meta-scrub + research-tooling relocation + doc gaps (perfectionist pass PR-3)

[KedoKudo]

PR-3 — the final queue item of the pre-paper perfectionist pass (after #610 claim accuracy, #611 exact Doppler kernel, #612 MIT/metadata). The repository's prose now reads for a cold reviewer: no review-process metadata in production comments, no citations to artifacts a reader cannot open, no research-only tooling shipped in-tree, and the flagship API documented.

Net: −1592 lines (+707/−2299 across 48 files).

What changed

Meta scrub (~205 sites)

House rule: a comment says why the code is shaped this way; when / which PR / which reviewer lives in commit messages and PR bodies, where git preserves them.

• ~140 reviewer/round/PR decorations stripped ("Codex round-3 P3 on PR PR 2b (#474 follow-up): wire SparseEmpiricalCubaturePlan into TransmissionFitModel + spatial_map + remove temp bindings #480", "Copilot review finding on PR perf(resolution): BCE-only ResolutionPlan::apply (21% on B.2, bit-exact) #470", "Independent review P1 reproduction", "epic Epic: multi-isotope forward-model acceleration (sparse empirical cubature + scalar branch) #472, PR PR 3 of #472: scalar k=1 fast-path — Gauss-quadrature vs Chebyshev-in-density, decide by measurement #475"). Every carried fact stays inline ("Codex PR PR 3 of #472: scalar k=1 fast-path — Gauss-quadrature vs Chebyshev-in-density, decide by measurement #475 round 2 measured 73 % rel err" → "measured: 73 % rel err"). Issue anchors (Defects surfaced by spatial+TZERO notebook (follow-up to #448) #458, [bug-hunt] LM fit cached path + jacobian resolve on coarse grid (no aux grid) — baseline-affecting #608, feat(fitting): user-specifiable fit energy range (SAMMY REGION equivalent) #514…) stay — issues are the durable what-record. Algorithm terms (round-trip, round-off) and SAMMY manual citations untouched.
• ~16 meta-only test docstrings ("Regression for Round-2 review fix Phase 0: Expand nereids-core with full type/trait/error system #4") rewritten to state the pinned invariant.
• ~65 private-memo citations ("memo 35 §P1.2", "memo 38 §6", benchmark shorthand "EG2 S2 C_An", "EG5") replaced with their content — including the Python API stubs, PyO3 rustdoc, GUI hover text, and user-facing error message strings. Two memory-file pointers and the codex04 design-study contestant name neutralized; the surrogate module doc keeps its full math + measured-compression table under neutral study provenance.
• .research/ paths removed from every tracked file (rustdoc, tests/data README, the PR template) — including the VENUS npz fixture's embedded description field (regenerated; all six data arrays verified bitwise identical).

Research tooling out of the repo

The 14 scripts/perf/* profiling drivers and 2 scripts/fixtures/extract_venus_*.py extractors exist only to read the private 38 GB VENUS cube; they now live with that data outside the repository (path depth, internal invocation paths, and SAMMY EMIN/EMAX wording updated; py_compile/bash -n verified; zero executable wiring referenced them). Public docs describe the provenance without naming paths nobody else has.

Doc gaps closed

• spatial_map_typed — the pipeline's flagship spatial entry point had zero rustdoc; now documents input modes, the full up-front validation contract (per-domain value checks, active-bin scoping, the three rejected degenerate configs and why each would otherwise produce a silently all-NaN map), rayon parallelism, cancel/progress semantics, and the error variants.
• lib.rs module lists for pipeline/io/fitting (9 modules were missing); descriptions taken from each module's own header. The hdf5-gated entries are deliberately not intra-doc links so standalone cargo doc -p nereids-io stays warning-free (verified).
• 13 in-test println!s gone (11 pure dumps removed; the fixture-missing skip notice → eprintln!; the parser's summary prints → a real contract assertion). The deliberate measurement eprintln!s (samtry, VENUS, Doppler) untouched. Bare unreachable!() in the penetrability test helper now states its invariant.

Two real fixes the review process forced

1. Cancellation contract (round 2): the new rustdoc promises PipelineError::Cancelled on every cancellation path, but the fit_temperature base-XS precompute wrapped its error with .map_err(PipelineError::Transmission), bypassing the purpose-built From conversion — a user cancelling during the expensive Reich-Moore precompute got an error toast instead of a clean cancel. Fixed with bare ? + a mutation-checked (3/3) regression test with engineered timing windows (caller-supplied precomputed XS removes the earlier window; a 100k-point grid stretches the target window to tens of ms; the assertion is timing-independent so the test cannot flake).
2. Real-VENUS counts-KL regression gate (round 1): the scrub's reworded docs claimed real-data validation that no in-tree artifact substantiated. Instead of weakening the words, the new test_counts_kl_fit_matches_baseline runs the joint-Poisson fit on the committed aggregated VENUS Hf fixture: anchored density (2.911e-5) + deviance/dof (3.14e4 — the documented real-data saturation regime, asserted ≫ 1) + an anchor-independent physical bracket. Python suite 127 → 128.

Review

/review-pipeline, 3 cross-family rounds (Claude + Codex):

Round	Outcome
1	1 VERIFIED P1 (my own rewrite misattributed the polish benchmark to "real VENUS data" — the scrub pass introducing a claim-accuracy bug, caught and fixed) + 1 NEEDS-VERIF P1 (resolved with the new real-data gate) + 7 P2s fixed
2	0 blocking; Codex's circularity P1 refuted (docs make two distinct claims — synthetic-validated vs regression-locked — and the test self-discloses its anchor role); 4 P2s fixed incl. the Cancelled-contract code fix
3	0 blocking; Codex's timing-test P1 refuted by direct measurement (verifier compiled a timing probe: 17/17 runs land in the changed call site, 25× debug margin); 4 P2s fixed incl. the standalone-doc-build breakage the reviewer empirically reproduced

Acceptance grep gates (all clean)

• .research appears in no tracked file outside .gitignore, CHANGELOG history, and agent-process docs — including inside binary fixtures;
• Codex|Copilot|codex04|memo 35|memo 38|EG[0-9]|round-N P[0-9]-class tokens: zero hits across crates/bindings/apps/tests;
• scripts/perf|extract_venus: zero hits.

Gates

fmt · clippy -D warnings · cargo test --workspace (22 binaries, 0 failures; pipeline suite +2 tests) · cargo doc -D warnings (workspace and standalone nereids-io) · mdBook · maturin build · pixi run test-python (128 passed).

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 93.75000% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.63%. Comparing base (3c5f6ea) to head (47e97fb).

Files with missing lines	Patch %	Lines
crates/nereids-pipeline/src/spatial.rs	92.30%	4 Missing ⚠️
crates/nereids-physics/src/penetrability.rs	0.00%	1 Missing ⚠️
crates/nereids-physics/src/reich_moore.rs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #614      +/-   ##
==========================================
+ Coverage   91.59%   91.63%   +0.03%     
==========================================
  Files          46       46              
  Lines       32227    32283      +56     
==========================================
+ Hits        29518    29582      +64     
+ Misses       2709     2701       -8     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[KedoKudo]

Windows CI failure + codecov disposition (addressed in 47e97fb):

• Test (windows-latest): the pre-existing test_spatial_map_mid_run_cancellation_returns_err lost its watcher race on the saturated runner — the busy-spinning watcher thread was starved until all 64 pixels and the post-loop cancel check completed, producing a COMPLETE Ok map (n_converged: 64/64), which the test wrongly treated as the regression. The test now distinguishes the three outcomes — Err(Cancelled) passes, a complete map is an inconclusive race-loss and retries (bounded), a partial map (the actual regression it guards) fails immediately — and the watcher yields instead of spinning.
• Codecov patch (3 lines, status checks already green): the pipeline.rs miss was the reworded "B_det wiring is deferred" error string, whose gate (non-zero detector_background under joint-Poisson) had no test — a real contract test now covers it. The other two are unexecutable-by-design: the unreachable! message in penetrability's test helper (executes only if the invariant breaks) and the Hf-177 fixture-missing skip notice in reich_moore (executes only on broken checkouts).

[Copilot]

Pull request overview

This PR performs a broad “meta scrub” and documentation hardening pass aimed at making the repository readable and self-contained for external reviewers, while relocating research-only tooling out of the tracked tree and adding/strengthening a couple of regression gates tied to committed VENUS fixtures.

Changes:

• Remove review/round/PR/memo-style metadata from in-tree prose (rustdoc, tests, GUI strings, templates) while preserving the underlying technical facts.
• Relocate/remove research-only VENUS extraction + performance profiling scripts from the repository; update fixture provenance docs accordingly.
• Close key doc/testing gaps: add substantial rustdoc for spatial_map_typed, ensure cancellation maps to PipelineError::Cancelled, and add a real-VENUS counts-KL regression gate in Python tests.

Reviewed changes

Copilot reviewed 47 out of 48 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/test_nereids.py	Scrubs review metadata in docstrings/comments and adds a real-VENUS counts-KL baseline regression test using committed fixtures.
tests/test_mcp.py	Removes review-metadata phrasing from docstrings/comments in MCP-facing tests.
tests/data/README.md	Updates VENUS fixture provenance/regeneration guidance without referencing private repo paths; documents the aggregated NPZ fixture.
scripts/python_api_allowlist.txt	Removes private memo reference from API allowlist commentary.
scripts/perf/summarize_sample.py	Removes research-only profiling helper script from the tracked tree.
scripts/perf/run_sample.sh	Removes research-only macOS sampling wrapper script.
scripts/perf/run_sample_kl_periso_tzero.sh	Removes research-only macOS sampling wrapper script.
scripts/perf/run_sample_b3.sh	Removes research-only macOS sampling wrapper script.
scripts/perf/run_sample_b2.sh	Removes research-only macOS sampling wrapper script.
scripts/perf/run_sample_b2_at_scale.sh	Removes research-only macOS sampling wrapper script.
scripts/perf/run_sample_b1.sh	Removes research-only macOS sampling wrapper script.
scripts/perf/profile_kl_periso_tzero.py	Removes research-only profiling driver referencing private data paths.
scripts/perf/profile_b3_lm_periso_tzero.py	Removes research-only profiling driver referencing private data paths.
scripts/perf/profile_b2_kl_grouped.py	Removes research-only profiling driver referencing private data paths.
scripts/perf/profile_b2_kl_grouped_at_scale.py	Removes research-only profiling driver referencing private data paths.
scripts/perf/profile_b1_lm_tzero_grouped.py	Removes research-only profiling driver referencing private data paths.
scripts/perf/profile_a1_lm_grouped.py	Removes research-only profiling driver referencing private data paths.
scripts/perf/baseline_dump.py	Removes research-only baseline dump/verify harness from the tracked tree.
scripts/fixtures/extract_venus_hf_nexus.py	Removes fixture extractor that depended on private VENUS cube; tooling moved out-of-repo.
scripts/fixtures/extract_venus_aggregated.py	Removes aggregated VENUS extractor that depended on private VENUS cube; tooling moved out-of-repo.
crates/nereids-pipeline/src/spatial.rs	Adds comprehensive rustdoc for spatial_map_typed, fixes cancellation error mapping in the temperature precompute path, and adds/updates cancellation regression tests.
crates/nereids-pipeline/src/pipeline.rs	Updates joint-Poisson / counts-KL documentation and error messages to remove private memo anchors; adds a deferred-feature rejection test for non-zero detector background.
crates/nereids-pipeline/src/lib.rs	Completes module list in crate-level rustdoc for pipeline crate.
crates/nereids-physics/tests/venus_usr_surrogate.rs	Rewords design-study provenance text to remove contestant naming while keeping the technical claim.
crates/nereids-physics/src/transmission.rs	Scrubs review metadata from doc comments in the transmission module.
crates/nereids-physics/src/surrogate.rs	Generalizes design-study provenance wording and removes .research/ references while preserving math/measurement content.
crates/nereids-physics/src/slbw.rs	Removes debug println! noise from tests.
crates/nereids-physics/src/resolution.rs	Scrubs review-metadata phrasing from safety/docs/tests while preserving invariants and rationale.
crates/nereids-physics/src/reich_moore.rs	Removes debug println!s from tests and changes a skip notice from stdout to stderr.
crates/nereids-physics/src/penetrability.rs	Replaces bare unreachable!() with an invariant message in a test helper.
crates/nereids-io/src/project.rs	Removes memo references from project snapshot field docs.
crates/nereids-io/src/nexus.rs	Updates rustdoc to avoid referencing removed in-repo extractors while preserving the units/back-compat contract description.
crates/nereids-io/src/lib.rs	Expands module list documentation (including non-link entries for hdf5-gated modules to keep standalone doc builds warning-free).
crates/nereids-fitting/src/transmission_model.rs	Scrubs PR/review references and tightens explanatory comments around surrogate dispatch guards.
crates/nereids-fitting/src/poisson.rs	Updates module docs to remove memo references while retaining the distinction between legacy helpers and production counts-KL path.
crates/nereids-fitting/src/nelder_mead.rs	Rewrites motivation docs to remove private benchmark shorthand while preserving the performance/correctness rationale.
crates/nereids-fitting/src/lm.rs	Cleans up regression-test doc comments to remove review-round metadata.
crates/nereids-fitting/src/lib.rs	Completes crate-level module list documentation.
crates/nereids-fitting/src/joint_poisson.rs	Removes .research//memo references from module/docs and clarifies the validation/regression-gate narrative.
crates/nereids-endf/src/parser.rs	Replaces test println! output with an assertion that checks an invariant (total resonance count covers resolved sum).
bindings/python/src/lib.rs	Scrubs memo references in PyO3-facing doc comments and keeps the binding-side validation narrative intact.
bindings/python/python/nereids/init.pyi	Updates stub docstrings to remove memo anchors and reflect the real-VENUS regression gate claim.
apps/gui/src/widgets/design.rs	Updates GUI overlay rationale comment to avoid memo references while pointing to the underlying pipeline behavior.
apps/gui/src/state.rs	Removes memo references from persisted GUI state field docs.
apps/gui/src/guided/result_widgets.rs	Rewords GOF labeling comment to remove memo anchor.
apps/gui/src/guided/analyze.rs	Cleans hover/help text and result-label comment to remove memo references while preserving the user-facing meaning.
.github/pull_request_template.md	Removes .research/ path mention and rephrases process guidance without review-metadata jargon.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.