codex-py/docs/coldstart-evaluate-review-release.md

Cold-start session prompt — evaluate open points · review · release

Paste the block below into a fresh Claude Code session (it assumes no memory of prior work).

---

You are picking up codex-py cold. The data-quality roadmap (DQ-1–DQ-5 + R-A–R-F) was merged to main via PR #16 (merge commit 5aa2f7d). Your job this session, in order: (1) evaluate the remaining open points, (2) code-review the released state, (3) cut a release. Read the two handoff docs first, then work the tasks. Ask before any destructive action (branch deletion) or before publishing the release.

Orient yourself first

• Repo: /Users/tarikmoussa/Desktop/codex-py, branch main (at the PR #16 merge).
• Read: docs/SESSION-2026-06-17-open-items.md (open items + branch-cleanup lists), docs/audit/DATA-QUALITY-2026-06-15.md (DQ-1–DQ-5 + R-A–R-F resolution blocks), docs/infra/jetson-ssh-stability.md (infra TODO), docs/infra/grobid-jetson.md.
• Live DB: Jetson Postgres via SSH tunnel ssh -o ServerAliveInterval=15 -f -N -L 5433:localhost:5432 alfred@jetson.local; creds in .env.jetson-ingest. The tunnel is chronically flaky — prefer short, idempotent ops; for long live runs use tmux on the Jetson (no tunnel needed there).
• Tests: PYTHONPATH=. .venv/bin/python -m pytest -q. Important: importing codex eagerly loads the embedding libs (~2 min) so the suite is slow, and this sandbox auto-backgrounds + reaps long commands. Launch ONE pytest run and issue no other commands until it notifies you — that lets it finish (polling its output file with a read-only Read is fine; a new Bash command reaps it). Baseline after PR #16: 408 green.
• Remote: origin = git.eulernest.eu/user2595/codex-py. Use the gitea MCP for PRs/tags/releases (tools mcp__gitea-eulernest__*).

Task 1 — Evaluate open points

• Branch cleanup: confirm these are fully merged into main, then propose deletion (local + remote): feat/tex-ingest, feat/crossref-references, feat/graph-coverage-warning, feat/section-labels, chore/infra-ssh-stability, audit/loop-1, integration/roadmap; plus pre-session stale: feat/F-15-literature-graph, feat/F-16-chunk-quality, fix/audit-wave-1/2/3, scratch/spike-embed.
• Deferred review findings (intentionally left in PR #16 — see the fix(review) commit): #3 (chunk_sections drops pre-\section text), #8 (script id-normalizer duplication), #9 (arXiv cited-id case), #11 (gzip heuristic), #12 (title truncation). Re-assess whether any is worth doing now.
• Infra TODO: tmux-on-Jetson for stable long ops — documented, not implemented.
• DQ-6 (upstream PDF→.txt fidelity) — flagged, believed mooted by R-A/R-C; confirm.
• If the tunnel is up, a quick corpus scan for any new data-quality gap.

Task 2 — Review

• Run /code-review on main (the released state) and confirm no regressions.
• Confirm the full suite is green (pytest -q, honoring the launch-and-wait rule), plus ruff check, ruff format --check, mypy codex/ scripts/.

Task 3 — Release

• Only after the review + suite are green.
• Bump the version in pyproject.toml (currently 0.1.0; the roadmap is a substantial feature set → 0.2.0). Commit on a branch (do not commit straight to main) and PR it, or tag the merge commit directly if that matches the team's flow.
• Write release notes summarizing DQ-1–DQ-5 + R-A–R-F + the audit-remediation reconcile; corpus impact: citations 590→1075, citing coverage 29/29, section signal 10%→95%.
• Create the tag + Gitea release via the gitea MCP; confirm it's published.

Deliverable: a short report of (1) the open-point decisions, (2) the review outcome, (3) the published release tag/URL.