Tracking: remaining work-plan backlog (items 2, 5–17)

[wiyth00]

Tracking issue for the work-plan items not yet on a branch. Shipped so far: #5 (item 1), #6 (item 9), #7 (item 4), and #8 (item 3, filed separately as a real bug).

Ground rules still apply: one PR per item, fix/ feat/ chore/ branches, squash-merge, every bug fix ships a regression test that fails on main first, and the published baseline (838 km / 3344 kg·m⁻³, mass 8.2430310159e21 kg, 2026-08-12 chained event) must not move unless the PR is explicitly labelled results-changing.

Needs a maintainer decision before code

• 2 — Dead candidate loop in perigee_state_for_position. Two ascending-node candidates are computed, then if best_state is None means the second is never evaluated; there is no scoring and the loop is dead. Choose (a) score both candidates and keep the prograde / lower two-body-error one, or (b) delete the loop and document why candidate Repo hygiene: CI triggers, coverage, Dependabot, templates, changelog #1 is the intended geometry. (a) is preferred but may reseed refine_design_shooting — results-changing, needs a before/after design_mode_event.json diff.
• 5 — config/baseline.yaml declares knobs the code ignores. The whole geometry: section, several optimization.* keys, and stability.years/samples/integrator/include_earth_j2/optional_long_years are never read. Each key must be wired through or deleted; add a strict validator that rejects unknown keys. Silent no-op config is a reproducibility hazard. Wiring is only a no-op if the wired values equal today's hardcoded ones (120 s tracks, 20/60 s brackets, 500 samples) — assert that in tests.
• 7 — _best_common_location is a 9-point line search. Replace the coarse scan with scipy.optimize.minimize_scalar on the geodesic fraction, same scoring function. Results-changing: shifts reported best-site coordinates; definition_a/definition_b need re-verifying on the 2026-08-12 event. Explicit approval required.
• 11 — Cut the v0.1.0 release. CITATION.cff claims date-released: 2026-07-13, the README links releases/latest, and CHANGELOG.md compare links point at v0.1.0 — none of which exist. Needs a maintainer to pick the tag target and upload the run bundle/movies the README promises.

Ready to implement

• 6 — Three duplicate numeric implementations. Kepler solvers (orbital_dynamics.solve_kepler vs stability._solve_kepler), element→state (elements_to_state vs orbital_elements_to_icrf_state), and geodesics (hand-rolled Vincenty in validation.wgs84_geodesic_distance_km vs pyproj.Geod). Add cross-check tests first (<1e-12 on a (e, M) grid; <1 mm and <1 µm/s on an elements grid; <1 mm vs Geod.inv), then pick one canonical implementation. Unblocked for the geodesic half now that fix: declare pyproj as a direct dependency #5 makes pyproj a declared dependency.
• 8 — Single-source the version. Derive __version__ from importlib.metadata.version("chained-eclipse") with a PackageNotFoundError fallback of "0+unknown"; keep MODEL_VERSION deliberately separate and documented as a model version; add tests/test_versions.py asserting CITATION.cff's version: matches the installed package version.
• 10 — Enforce formatting. One mechanical ruff format . commit with no logic changes, then add .venv/bin/ruff format --check . to the CI Lint step.
• 12 — Entry-point cleanup. Delete run_search.py (duplicates the chained-eclipse console script) and update the README quick-start to uv run chained-eclipse --mode full. Drop chained-eclipse-eclipse4-atlanta and chained-eclipse-total-tracks-2027 from [project.scripts] — one-off analyses should not land on every user's PATH — keep them runnable via python -m chained_eclipse.… and say so in the README.
• 13 — Ephemeris kernel integrity verification. ephemeris.load_ephemeris() auto-downloads de440s.bsp with no checksum. Add a known-good SHA-256, verify on load, raise clearly on mismatch with an --allow-unverified-ephemeris escape hatch, and record verified: true/false in the events.json ephemeris block. The SHA-256 plumbing already exists (cli.run_full hashes the kernel after the fact for the manifest). Recommended first feature — the whole validation chain rests on kernel identity.
• 14 — Hybrid (annular-total) eclipse classification. Classification happens at the greatest-eclipse point only, so a hybrid gets mislabelled total or annular and type_matches fails spuriously. Sample the signed core radius along the track (iter_real_track already yields it) and classify hybrid on a sign change; add a NASA hybrid reference (e.g. 2031-11-14) and extend the type-match logic. Labels only — timings and coordinates unchanged, but flag any catalog rows whose label moves.
• 15 — --version flag + structured logging. argparse --version printing package version, MODEL_VERSION, and kernel name; replace bare print(..., flush=True) progress lines in cli.py with logging (INFO default, --quiet/--verbose), keeping terminal_summary.txt byte-identical.
• 16 — Stage checkpointing for run_full. A failure at stage 5 currently discards hours of stages 1–4. Add --resume: reuse a stage's output JSON when its recorded model_version and config hash match. Stages already write real_moon_eclipses.json, validation_report.json, design_mode_event.json, and stability.json, so this is mostly plumbing plus a config-hash field. Must refuse to resume across a differing MODEL_VERSION or kernel SHA — depends on item 13.
• 17 — Broaden the validation set. All four references sit within 2 years of epoch. Add a pre-epoch historical eclipse (2017-08-21 or 2024-04-08), a deep partial with no central line (requires extending _validate_one to compare penumbral geometry), and a hybrid (after item 14). Turns validation from a near-epoch smoke test into a real accuracy envelope.

Suggested order

1. 12 — trivial, zero-risk
2. 8, 10 — small and independent
3. 6 — numeric care needed, tests first
4. 13, 15 — small features, high value
5. 5, 14, 16, 17 — larger; results-affecting bits need sign-off
6. 2, 7, 11 — gated on maintainer decisions

[wiyth00]

Progress update — three more items are now on PRs:

• 12 — entry-point cleanup → chore: entry-point cleanup — delete run_search.py, prune one-off console scripts #10 (deletes run_search.py, prunes the two one-off console scripts, README now uses uv run chained-eclipse)
• 8 — single-source the version → chore: single-source the package version; pin CITATION.cff to it in tests #11 (__version__ from importlib.metadata, tests/test_versions.py pins CITATION.cff to the package version; MODEL_VERSION deliberately untouched)
• 13 — kernel integrity → feat: verify ephemeris kernel integrity on load #12 (trust-on-first-use sidecar + empty KERNEL_SHA256_PINS table; NAIF publishes no checksums, so the known-good pin must come from a maintainer's local sha256sum data/ephemeris/de440s.bsp — one-line follow-up)

Follow-ups that moved here from #12's scope:

• Wire --allow-unverified-ephemeris through cli.py and record kernel_sha256 / verified in the events.json ephemeris block + run manifest (do together with item 15, which touches the same argparse setup)
• Pin the de440s digest in KERNEL_SHA256_PINS from a trusted local copy

Still open, unchanged: 2, 5, 7, 11 (maintainer decisions), 6, 10, 14, 15, 16, 17 (implementable). Note for 10: the mechanical ruff format . commit has to be run locally — formatting by hand without running ruff would guarantee drift from what ruff format --check expects in CI.

[wiyth00]

Status update — remaining agent-executable work-plan items are now all in open PRs:

Item	PR	Status
6 — numeric cross-checks + scalar high-e Kepler fix + pyproj geodesic delegation	#13	CI ✅
15 — --version, logging with --quiet/--verbose	#14	CI ✅
16 — --resume per-stage artifact reuse (refuses across model-version/kernel changes)	#14	CI ✅
14 — hybrid (annular–total) classification + NASA 2031-11-14 hybrid reference	#15	CI running
17 — 2024-04-08 pre-epoch total + 2025-03-29 timing-only partial references	#16	CI running

Follow-ups from my earlier comment that are now resolved by PR #14:

• --allow-unverified-ephemeris escape hatch is wired through all five run modes.
• events.json now records the kernel's verified status from the load-time integrity check (no re-hash).

Merge-order notes:

• Classify hybrid (annular-total) eclipses; add NASA 2031 Nov 14 hybrid reference (item 14) #15 appends to the end of NASA_GSFC_REFERENCES; Expand validation references: 2024 pre-epoch total + 2025 timing-only partial (item 17) #16 inserts at the beginning; both keep the tuple chronological (and Expand validation references: 2024 pre-epoch total + 2025 timing-only partial (item 17) #16 adds a test enforcing that), so they merge cleanly in either order. Expand validation references: 2024 pre-epoch total + 2025 timing-only partial (item 17) #16's single cli.py hunk is disjoint from CLI: --version, logging with --quiet/--verbose, ephemeris verification wiring, and --resume (items 15 + 16) #14's logging changes.
• Classify hybrid (annular-total) eclipses; add NASA 2031 Nov 14 hybrid reference (item 14) #15 changes computed results (eclipse type labels for genuinely hybrid rows) — recommend re-running the catalog and diffing the eclipse_type column after merge.

Still maintainer-gated (no action from me): items 2, 5, 7, 11 per the ground rules; item 10 needs a local ruff pass decision.