build: production Windows release pipeline (PyInstaller, SBOM, CI, signing hook)

docs/RELEASE_PROCESS.md

@@ -1,20 +1,92 @@
 # Release Process
-<!-- stewardship-standard: release-process-v1 -->
 
-## Before Tagging
+Production Windows builds use **PyInstaller** with a gated pipeline in `scripts/release_build.ps1`.
 
-- Confirm the default branch builds, runs, or flashes as documented.
-- Confirm no secrets, private data, generated dependency trees, or raw binaries are accidentally committed.
-- Confirm license and upstream provenance are documented.
-- Update CHANGELOG.md.
-- Attach binaries only as release assets with SHA256 checksums and source commit references.
+## Quick commands
 
-## Release Notes
+| Goal | Command |
+|------|---------|
+| **Production release** | `build_release.bat` or `powershell -File .\scripts\release_build.ps1` |
+| **Dev build (Desktop copy)** | `build_exe.bat` or `powershell -File .\scripts\setup_and_build.ps1` |
+| **Skip tests (dev only)** | `powershell -File .\scripts\setup_and_build.ps1 -SkipTests` |
 
-Include:
+## Production pipeline (`release_build.ps1`)
 
-- Purpose of the release.
-- Commit hash or tag.
-- Build environment.
-- Known limitations.
-- Verification performed.
+1. Resolve Python 3.10+
+2. Install `requirements.txt` + `dev-requirements.txt` (PyInstaller **6.10.0** pinned)
+3. **Test gate**: `compileall` + `unittest discover` (skip with `-SkipTests` — not for prod)
+4. Download & SHA-verify bundled `gost.exe` → `proxy_chain_manager/_bundled/`
+5. Generate Windows **VERSIONINFO** → `build/version_info.txt`
+6. **PyInstaller** one-file build via `ProxyChainManager.spec`
+7. Optional **Authenticode** sign (see below)
+8. SHA256 sidecar for the exe
+9. **SBOM** (`SBOM.json` + `requirements-frozen.txt`)
+10. **RELEASE_MANIFEST.json** (version, commit, sha256, build time)
+11. Zip → `releases/ProxyGod-v{version}-windows-amd64.zip`
+
+### Output layout
+
+```
+releases/
+  v1.0.0/
+    ProxyChainManager.exe
+    ProxyChainManager.exe.sha256
+    RELEASE_MANIFEST.json
+    SBOM.json
+    requirements-frozen.txt
+    LICENSE
+    OPERATOR_RUNBOOK.md
+  ProxyGod-v1.0.0-windows-amd64.zip
+dist/
+  ProxyChainManager.exe          # same binary (developer convenience)
+  ProxyChainManager.exe.sha256
+```
+
+## Version numbering
+
+Resolved in order:
+
+1. `-Version` parameter to `release_build.ps1`
+2. Exact git tag on current commit (`git describe --tags --exact-match`)
+3. `git describe --tags --always --dirty`
+4. `proxy_chain_manager.__version__`
+
+Tag releases with `v1.2.3` — CI **release.yml** runs automatically on `v*` tags.
+
+## Authenticode signing (optional)
+
+Set before building:
+
+```powershell
+$env:SIGN_CERT_PATH = "C:\certs\proxygod.pfx"
+$env:SIGN_CERT_PASSWORD = "your-password"   # optional if pfx has no password
+powershell -File .\scripts\release_build.ps1
+```
+
+Requires **Windows SDK** (`signtool.exe` on PATH). Without a cert, the build completes unsigned (SmartScreen may warn on first run).
+
+## CI / GitHub Releases
+
+- **Every push/PR**: `.github/workflows/test.yml` — unit tests only
+- **Tag `v*` or manual dispatch**: `.github/workflows/release.yml` — full release build + artifact upload + GitHub Release assets
+
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+## Before tagging (checklist)
+
+- [ ] `python -m unittest discover -s tests -v` passes locally
+- [ ] CHANGELOG.md updated
+- [ ] No secrets in `settings.json` / signup JSON committed
+- [ ] `proxy_chain_manager/_bundled/gost.exe` will be fetched at build time (or pre-staged)
+- [ ] Verify SHA256 after build: `Get-FileHash releases\v*\ProxyChainManager.exe -Algorithm SHA256`
+
+## Verify a release artifact
+
+```powershell
+Get-FileHash -Algorithm SHA256 releases\v1.0.0\ProxyChainManager.exe
+Get-Content releases\v1.0.0\ProxyChainManager.exe.sha256
+Get-Content releases\v1.0.0\RELEASE_MANIFEST.json | ConvertFrom-Json
+```