Align release guide and commands with research-repo-tools evidence-reuse flow #330

Summary

Target v0.5.3. Update docs/RELEASING.md so the maintainer verifies the exact merged release commit before creating or pushing its tag. Keep the current v0.5.2 release scope and retained benchmark evidence unchanged.

Current State

The release guide, inspected on 2026-10-29, currently orders synchronization, tag creation, tag push, then just release-evidence. Git push itself does not wait for or verify CI. The evidence recipe checks the checkout's commit and package version and does not require an existing tag.

Proposed Changes

Make the documented post-merge sequence:

1. Synchronize a clean checkout to the exact reviewed commit on main; record its full SHA.
2. Wait for that commit's complete eligible main-push CI run, including native builds, default/exact Cargo packaging, and evidence signing. Check the separately required Clippy SARIF and Repository Rule SARIF results.
3. Run just release-evidence successfully before any tag mutation.
4. Create and inspect the annotated tag with just tag "$TAG"; confirm it resolves to the verified SHA.
5. Push the tag, then continue the existing draft, benchmark-asset, reviewed publication, approval, and registry-verification steps.

Clarify that release-evidence verifies the declared CI evidence, not every independent workflow. Preserve publication-time and post-approval revalidation. If HEAD or the selected run/attempt changes, repeat the applicable verification; do not substitute PR, manual-dispatch, partial-rerun, missing, or expired evidence.

Benefits

Detects release eligibility failures before publishing a tag and gives maintainers a consistent release sequence across the Rust repositories.

Implementation Notes and Acceptance

• Update numbered steps, Contents links, recovery instructions, and any references to the old step order.
• Verify implementation commands against the public installed tooling at the authorized exact development pin and the repository's current recipe/policy. release: plan, publish and verify la-stack v0.5.3 #333 owns repeating verification against the final normally resolved published version. The separately requested dispatch recipe is included below.
• Preserve exact-commit CI checks, signed evidence, benchmark provenance, deployment approval, and immutable-release safeguards.
• Run Markdown formatting/checks, spelling, and the repository's documentation checks. Inspect links and the complete procedure without tagging, publishing, or benchmarking.
• Limit implementation changes to the requested recipe/workflow wiring and its focused validation; preserve library code, scientific workload definitions, retained reports, and raw measurements. This issue is not a blocker for v0.5.2 / release: publish and verify v0.5.2 #311.
• Astra is not required for the guide reorder or simple dispatch forwarding; escalate if workflow alignment changes a trust contract.

The guide is outside the captured source/harness inventories: a standalone wording change would not invalidate v0.5.2 measurements. Deferral avoids another release-commit/CI iteration; it is not a benchmark-integrity requirement.

Cross-repository alignment

Related implementation and guide issues: #330, acgetchell/delaunay#672, acgetchell/markov-chain-monte-carlo#220, and acgetchell/causal-triangulations#321. These can proceed independently; the common contract is exact-commit evidence verification before tag creation/push, with each repository's required checks and publication safeguards preserved.

Canonical release benchmark dispatch

Also implement the same maintainer-facing recipe in each repository:

just release-benchmarks "$TAG"

• Add one canonical release-benchmarks tag recipe that dispatches release-benchmarks.yml with both --ref "$TAG" and -f tag="$TAG", passing the single required argument safely. Do not default to main, infer a tag, or add aliases.
• Align the workflow's required input with the canonical tag name and update every affected caller/test. Repositories currently using release_tag need the recipe and workflow migration together; do not dispatch an undeclared input.
• Preserve or establish preflight verification that the workflow ref is refs/tags/<tag>, its source SHA matches the resolved tag, and the captured mutable stable draft has the expected tag/title. Preserve trusted-runtime boundaries, concurrency, raw samples, asset identity, and upload safeguards; keep each repository's scientific workloads and package type.
• Update docs/RELEASING.md and command discovery to use this recipe after successful evidence verification, tag push, and draft availability. Keep the expanded gh command only where useful for troubleshooting. The recipe dispatches and returns; it does not wait/poll, create tags/drafts, publish the release, invoke local acquisition, or run performance-readme.
• Validate exact argument/ref/input forwarding, required-tag handling, and propagation of dispatch failure using an isolated fake gh/existing test harness. Validate workflow syntax and ref/tag rejection through focused checks without starting a real benchmark run.

This dispatch recipe is a separate step from local performance-release preparation/acquisition and separately retryable performance-readme. Any workflow trust-policy change receives the applicable Astra checkpoint; a thin argument-forwarding recipe alone does not require Astra.

Canonical release-flow alignment — maintainer request, 2026-11-05

The maintainer designates research-repo-tools docs/RELEASING.md as the gold standard. Align this repository's guide and executable workflow with it: the common Step 1/Step 2 sections, operator-facing command names, argument meanings, ordering, evidence reuse, approval and retry behavior should be close to identical. Record the reference revision when implementing; do not merely rename an expensive command to release-evidence.

Required outcome

• Audit the current guide, Just recipes, main-CI producers, draft preparation and registry publication together. Record a concise command/behavior comparison and justify every repository-specific difference.
• Use the shared operator commands wherever the operation applies: update-version, changelog-release, release-version-check, publish-check, release-evidence, tag, release-notes, release-publish and release-verify. Match required arguments and side effects, without redundant aliases. Keep Cargo implementation and registry identity behind the appropriate commands.
• Step 1 prepares and validates the release. The eligible final-main CI attempt owns the required native tests and package verification. Step 2 inspects and reuses that retained evidence; it must not start another test matrix or repeat already-covered package-verification builds. Cargo's required nonbuilding repackaging/upload is a distinct operation and must be described accurately.
• Preserve explicit evidence verification before tag creation/push. Reconcile any ordering difference in the reference guide explicitly; do not weaken an existing pre-tag safeguard merely to match prose.
• Align tag-triggered draft preparation with the common automated flow, consuming retained evidence and generated notes. Routine instructions should not require manual temporary note files or ad hoc draft creation where the shared flow supports automation. Preserve draft-first asset attachment, immutable release rules and explicit maintainer publication.
• Coordinate the separately tracked benchmark-reuse issue: one Step 1 acquisition supplies reports, README and the durable release archive; Step 2 and publication retries verify/derive/attach without sampling again. Preserve performance-release, separately retryable performance-readme, and the canonical explicit-tag release-benchmarks "$TAG" dispatch. After adoption, that dispatch handles validated retained evidence rather than reacquisition.
• Keep package identity, registry setup, scientific/feature checks and benchmark requirements in short repository-specific declarations or clearly identified sections. Do not duplicate generic shared logic, claim that signed source evidence proves byte-identical Cargo archives, or substitute engineering checks for scientific guarantees.
• Preserve exact commit/run/attempt, signer, immutable artifact/digest, freshness and approval-time checks. Missing or changed evidence stops publication; it must not trigger a hidden rebuild or silently select replacement evidence.
• Focused integration tests make build/test/acquisition entry points fail if the Step 2 inspection or retry paths invoke them. Separately test legitimate nonbuilding Cargo publication, argument forwarding, invalid evidence and changed approval selections. Run the owning local/native checks for the adoption revision and demonstrate a real retained-evidence handoff.
• Update Contents, command discovery, guide links and recovery instructions together. Closure requires verified command/workflow behavior as well as near-identical common prose.

Astra reviews changes to evidence ownership, Cargo guarantees, signing, approval or scientific comparability. Sol is sufficient for settled-contract recipe wiring, documentation alignment and focused regressions. Earlier guidance that a simple reorder needs no Astra still applies to that narrow operation.

This issue owns release-flow parity; linked benchmark issues retain their implementation and scientific acceptance. These related changes can share a coherent PR without inventing mutual blockers. Existing milestones remain authoritative; publication-only gates are retained in #333 under the maintainer's 2026-11-07 handoff. No release, tag, benchmark campaign or account-setting change is performed by filing/updating this issue.

Current adoption boundary

As of 2026-11-07, PR #335 implements #323's benchmark evidence reuse, pre-tag verification, immutable transfer/approval ownership and explicit native CI renewal. It uses the authorized research-repo-tools development pin 055353c630604b1ae3438c1eaf534ba85e067a7e; required PR CI, review and merge remain separate.

This issue remains open for functional work: the canonical release-benchmarks recipe and focused forwarding tests, common command/guide parity and documented differences, and tag-triggered automatic draft preparation. At commit a2debb424426b75a97e8a56a061b70985f53d950, docs/RELEASING.md still creates the draft manually and dispatches release-benchmarks.yml directly. Reconcile that dispatch with #323's required explicit candidate/owner identity without weakening its trust contract. Finish the complete command/workflow comparison and remaining integration validation before closing this issue.

Publication-only acceptance has moved to #333: exact supplying v0.2.7/PyPI verification, normal dependency/lock/isolated-invocation updates, and final released-package/native revalidation. These obligations remain unchecked there and do not hold this implementation issue open by themselves. #326 retains the implementation-readiness handoff; #333 owns final adoption and actual release readiness. Existing unchecked items above describe the complete alignment audit and should be reconciled with #335's accepted contribution when the remaining work is implemented.