release — cut and publish a release

Wraps scripts/release and the Release GitHub Actions workflow (.github/workflows/release.yml). Do the version bump through the script — never hand-edit Cargo.toml/Cargo.lock versions or hand-craft the tag.

Preconditions (the script enforces these; check them first)

• On the release branch — main by default (override with POHUNEK_RELEASE_BRANCH). The script aborts if you are on another branch.
• Working tree is clean. Commit or stash first; the script aborts on a dirty tree.
• The gates pass on the commit being released. The Release workflow re-runs fmt/clippy/test (the nextest shards CI runs, plus doctests) + docs check on the tag, so a red commit publishes nothing — run the gates skill before tagging to fail fast locally.
• The target tag does not already exist.

Steps

1. Compare the compatibility constants. The script diffs these constants between the previous tag and HEAD: STORE_SCHEMA_VERSION (crates/daemon/src/store/), PROTOCOL_VERSION and MIN_PROTOCOL_VERSION (crates/protocol/src/version.rs), the worker protocol CURRENT_VERSION and PREVIOUS_VERSION (crates/worker-protocol/src/version.rs), WORKER_JOURNAL_SCHEMA_VERSION (crates/daemon/src/runtime/lifecycle.rs), and EXPECTED_INTEGRATION_VERSION (crates/protocol/src/integration.rs). Each one that changed alters the upgrade contract in .agents/instructions/project.md ("Upgrade window"), so the release needs a notes file with one line naming each changed constant and what an operator must do. Write it before the dry run and pass it as --notes FILE; the script aborts when a changed constant has no line.
2. Confirm the bump. Determine patch, minor, major, or an explicit X.Y.Z from the user's request ("minor release" → minor).

3. Dry-run first. Show what will happen without changing anything:

   scripts/release <patch|minor|major|X.Y.Z> [--notes FILE] --dry-run

   This prints the current and next version, the tag, the knowledge-log fragments the release would file, the folded CHANGELOG.md section that becomes the release body, and whether the release notes cover any changed compatibility constants. It also describes the commit, evidence checks, and pushes it would perform. Confirm that matches intent.

4. Cut the release. Run the real thing:

   scripts/release <patch|minor|major|X.Y.Z> [--notes FILE]

   The script files the docs/knowledge/log.d/ fragments under ## X.Y.Z in docs/knowledge/log.md and removes them (cargo xtask docs log fold), folds the changelog.d/ fragments into a ## X.Y.Z - <UTC date> section of the committed CHANGELOG.md and removes them (scripts/changelog fold), bumps version in [workspace.package] in Cargo.toml, refreshes Cargo.lock, commits all of it as Release vX.Y.Z, and requires successful main and nightly CI evidence for that commit before creating an annotated tag vX.Y.Z. Evidence is a run on the commit itself or a workflow_dispatch run that tested the same git tree; scripts/ci-evidence prints which run matched and whether by sha or by tree. By default it pushes the release branch before waiting for evidence and pushes the tag after verification. With --no-push, it checks only already-existing evidence and leaves the commit and tag local; it does not dispatch CI or push either ref. After local tagging, the script reminds you to push the release branch and tag manually. If the evidence check fails or times out, resolve the CI issue and rerun with the same explicit X.Y.Z; the workspace is already bumped, so do not request another relative bump such as patch.

5. Publish the notes. When a notes file was needed, attach it to the GitHub Release once the workflow has created it (gh release edit "vX.Y.Z" --notes-file FILE) and confirm with gh release view "vX.Y.Z".
6. Record the release. Via the github-workflow skill, comment the version/tag and release URL on any issue whose delivery this release completes (or opens a dedicated tracking issue beforehand when the release itself is planned work), and update the project status accordingly. Verify the writes from the API response.

7. Verify the Release workflow — do not trust, confirm. Pushing the vX.Y.Z tag triggers .github/workflows/release.yml, which runs the fmt/clippy/test gate + docs-gate, then builds pohunek and pohunekd for both x86_64-unknown-linux-gnu (dynamic glibc, primary) and x86_64-unknown-linux-musl (fully static, runs on any x86_64 Linux), packages per-component tarballs with sha256 checksums in read-only build jobs (release-build.yml), builds the official runtime package archives, runs the compatibility rows, assembles and signs the runtime catalog and rebuilds the daemon archives with a runtime/ directory (release-evidence.yml), runs the network-isolated archive smoke, and only then the single publish job (the only job with a write token, no checkout) verifies the complete inventory, creates a draft release, uploads and checks it, and publishes it. The TypeScript SDK tarballs pohunek-ts-{protocol,sdk,testkit}-X.Y.Z.tgz, each with a .sha256, are part of the same inventory. Watch it to completion:

   gh run watch "$(gh run list --workflow=release.yml --limit 1 --json databaseId --jq '.[0].databaseId')"
   gh release view "vX.Y.Z"   # confirm the tarballs + .sha256 (incl. the three pohunek-ts-*.tgz) are attached

8. Report. State the published version/tag, the workflow conclusion (success/failure with the failing job if any), and the attached artifacts. If the workflow failed, report why with output — a failed gate means no binary was published.

Constraints

• Never publish from a red commit; the workflow will block it, so catch it locally.
• Do not hand-edit versions or push a tag outside scripts/release.
• Verify the release actually published; never report "released" from the tag push alone without checking the workflow and the GitHub Release.