fix: create draft releases and defer cleanup until manual promotion

.github/workflows/release.yml

@@ -175,6 +175,7 @@ jobs:
       - name: Upload .deb and .rpm to release
         uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda  # v3.0.0
         with:
+          draft: true
           files: |
             dist/*.deb
             dist/*.rpm
@@ -289,6 +290,7 @@ jobs:
       - name: Upload ARM64 .deb and .rpm to release
         uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda  # v3.0.0
         with:
+          draft: true
           files: |
             dist/*.deb
             dist/*.rpm
@@ -436,6 +438,7 @@ jobs:
       - name: Upload .msi to release
         uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda  # v3.0.0
         with:
+          draft: true
           files: dist/*.msi
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -782,6 +785,7 @@ jobs:
       - name: Upload .dmg to release
         uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda  # v3.0.0
         with:
+          draft: true
           files: dist/*.dmg
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -843,6 +847,16 @@ jobs:
               continue
             fi
 
+            # ── Skip draft releases — they will be cleaned up after promotion ──
+            IS_DRAFT=$(gh release view "$TAG" \
+                        --repo "$REPO" \
+                        --json isDraft \
+                        --jq '.isDraft' 2>/dev/null || echo "false")
+            if [ "$IS_DRAFT" = "true" ]; then
+              echo "[${INDEX}] SKIP   ${TAG} (draft release — waiting for manual promotion)"
+              continue
+            fi
+
             echo "[${INDEX}] STRIP  ${TAG}"
 
             # ── Delete every existing asset on this release ──────────────────

RELEASE.md

@@ -0,0 +1,189 @@
+# Release Workflow & Promotion Checklist
+
+## Overview
+
+The `openstan` release process creates **draft releases** automatically via GitHub Actions when a version tag is pushed. Releases must be **manually promoted** from draft to published after verification and platform-specific checks.
+
+This approach prevents premature publication while allowing time to:
+- Verify all platform binaries are correct
+- Submit Windows MSI to Microsoft WDSI portal for SmartScreen clearance
+- Resolve any CI configuration issues without polluting the release history
+
+---
+
+## Quick Start: Create a Release
+
+### 1. Push a version tag
+
+```bash
+git tag v1.2.3
+git push origin v1.2.3
+```
+
+The tag must match the pattern `v*` (e.g. `v0.1.5`, `v1.0.0-rc1`). The workflow is triggered automatically.
+
+### 2. Wait for builds to complete
+
+All four platform jobs must complete successfully:
+- Linux (.deb + .rpm)
+- Linux ARM64 (_arm64.deb + .aarch64.rpm)
+- Windows (.msi)
+- macOS (.dmg)
+
+Monitor progress at: `https://github.com/boscorat/openstan/actions`
+
+Build time typically: **30–45 minutes** (varies by platform)
+
+---
+
+## Release Promotion Checklist
+
+Once all builds complete, the **draft release** will be created at:
+`https://github.com/boscorat/openstan/releases`
+
+Follow this checklist before promoting from draft to published:
+
+### Pre-Publication Verification
+
+- [ ] **All platform binaries attached**
+  - [ ] `openstan-X.Y.Z-Linux-Ubuntu-x86_64.deb` (64-bit)
+  - [ ] `openstan-X.Y.Z-Linux-Ubuntu-arm64.deb` (ARM64)
+  - [ ] `openstan-X.Y.Z-Linux-Fedora-x86_64.rpm` (64-bit)
+  - [ ] `openstan-X.Y.Z-Linux-Fedora-arm64.rpm` (ARM64)
+  - [ ] `openstan-X.Y.Z-Windows.msi` (Windows)
+  - [ ] `openstan-X.Y.Z-macOS.dmg` (macOS)
+
+- [ ] **Release notes are present and accurate**
+  - Describe key features, bug fixes, or changes
+  - Include any known issues or breaking changes
+  - Link to GitHub milestone/pull requests if applicable
+
+- [ ] **macOS .dmg is notarised**
+  - The workflow automatically handles code signing and Apple notarisation
+  - No manual action needed — if the macOS build succeeded, it's notarised
+  - Verify: Try opening the .dmg on a Mac; no Gatekeeper warnings should appear
+
+- [ ] **Windows .msi submission (WDSI portal)**
+  - [ ] Go to https://www.microsoft.com/en-us/wdsi/filesubmission
+  - [ ] Sign in with your Microsoft account
+  - [ ] Select "Software" → "Incorrect detection" → "Clean software"
+  - [ ] Upload the .msi file
+  - [ ] **Allow 24–48 hours for Microsoft to review**
+  - [ ] Once approved, SmartScreen warnings will be cleared
+
+  *Note: This step is critical if the Windows installer is to be widely distributed. SmartScreen reputation builds over time with downloads; without WDSI submission, Windows may initially warn users about the unsigned binary.*
+
+### No Breaking Changes?
+
+- [ ] Review changelog for any API or UI breaking changes
+  - If breaking changes are present, increment the **major** version
+  - Otherwise, follow semantic versioning (minor for features, patch for fixes)
+- [ ] All deprecation warnings added in previous releases are documented
+
+---
+
+## Manual Promotion: Draft → Published
+
+Once the checklist is complete and Microsoft has cleared the .msi (if applicable):
+
+### Option A: Using GitHub CLI
+
+```bash
+gh release edit v1.2.3 --draft=false
+```
+
+### Option B: Using GitHub Web UI
+
+1. Go to `https://github.com/boscorat/openstan/releases`
+2. Click on the draft release
+3. Click **"Edit"** (pencil icon, top-right)
+4. Uncheck **"This is a pre-release"** (if applicable)
+5. Uncheck **"Set as a draft"** checkbox
+6. Click **"Publish release"**
+
+### Result
+
+- Release is now **published** and visible to all users
+- Appears on the **Releases** page as a normal (not draft) release
+- May be tagged "Latest" if appropriate
+- Announcement can be made on social media, blog, etc.
+
+---
+
+## Post-Publication
+
+After publishing:
+
+- [ ] The **cleanup job** automatically runs after all builds
+  - Strips binaries from releases older than the **5 most recent**
+  - Leaves a `NOTICE.txt` pointing users to the latest version
+  - Keeps draft releases intact until they're manually promoted
+
+- [ ] Announce the release (if desired)
+  - GitHub Discussions
+  - Project website
+  - Social media
+  - Email newsletter
+
+---
+
+## Troubleshooting
+
+### Some platform jobs failed during build
+
+- Check the failed job logs: `https://github.com/boscorat/openstan/actions`
+- Common issues:
+  - **macOS notarisation timeout**: Apple's service occasionally stalls; the workflow retries up to 75 minutes. If it fails, re-run the macOS job from GitHub Actions UI.
+  - **Windows build timeout**: The WiX toolset can be slow; re-run if it hits the 30-minute timeout.
+  - **Linux dependency issues**: Check if system libraries are out of date on the runner; typically resolves on next run.
+- **Do not publish** if builds are incomplete — delete the partial draft release and push the tag again.
+
+### Draft release is missing binaries
+
+- Verify the tag matches the version in `pyproject.toml`
+- Check individual job logs to see which platform failed
+- Re-run failed jobs from the GitHub Actions UI
+- Alternatively, delete the tag, fix the issue, and push a new tag
+
+### Microsoft WDSI submission rejected
+
+- Review Microsoft's feedback in the submission portal
+- Common rejections: unsigned binary, wrong certificate, or binary has malware signatures (unlikely, but antivirus false positives happen)
+- Resubmit or contact Microsoft support if clarification is needed
+- Do **not** publish the release until WDSI clears it
+
+### Release was published but should have been draft
+
+You can revert a published release to draft:
+
+```bash
+gh release edit v1.2.3 --draft
+```
+
+This will immediately hide the release from the **Releases** page, but the tag and binaries remain.
+
+---
+
+## Reference: Version Tags
+
+- **Stable releases**: `v1.0.0`, `v1.2.3` — use semantic versioning
+- **Release candidates**: `v1.0.0-rc1`, `v1.0.0-rc2` — include `-rc` suffix
+- **Alpha/beta**: `v1.0.0-alpha1`, `v1.0.0-beta2` — include prefix and number
+- **Development/test**: `v0.0.0-test` — for testing the release workflow only (delete tag after testing)
+
+---
+
+## Reference: Workflow Files
+
+- **Main release workflow**: `.github/workflows/release.yml`
+- **CI pipeline** (runs on all commits): `.github/workflows/ci.yml`
+- **Cleanup** (strips old assets): `.github/workflows/release.yml` (cleanup job)
+
+---
+
+## Related Issues & Documentation
+
+- **Issue #81**: Release workflow should create draft releases
+- **Issue #76**: Review CI Release Pipeline (original checklist)
+- **AGENTS.md**: Code signing setup (Windows SignPath, macOS Developer ID)
+- **README.md**: Installation and user guide