docs: clarify release versioning checks

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: shanselman

docs/RELEASING.md

@@ -46,7 +46,16 @@ build/sign/publish release artifacts.
      --limit 10
    ```
 
-5. Confirm the GitHub release is a prerelease and not latest for alpha tags.
+5. Confirm the workflow used the exact tag SemVer. Tagged builds fail before
+   publishing if GitVersion disagrees with the tag name.
+
+   ```powershell
+   $version = $tag -replace '^v', ''
+   .\scripts\Get-OpenClawVersion.ps1 -Variable SemVer
+   # Expected: $version
+   ```
+
+6. Confirm the GitHub release is a prerelease and not latest for alpha tags.
 
    ```powershell
    gh release view $tag --repo openclaw/openclaw-windows-node `
@@ -217,5 +226,8 @@ Only tag when `HEAD == origin/master`.
 - Do not add csproj `<Version>` release fallbacks; product versions come from
   GitVersion/tag history.
 - Release versions come from the tag (`vX.Y.Z` or `vX.Y.Z-alpha.N`).
+- Untagged `master` builds are prerelease builds. After `vX.Y.Z-alpha.N`, an
+  untagged commit may resolve to the next alpha prerelease, for example
+  `X.Y.Z-alpha.(N+1)`.
 - CI computes GitVersion outputs for artifact naming, while product builds use
   GitVersion-backed assembly metadata.

docs/VERSIONING.md

@@ -15,6 +15,22 @@ imports GitVersion through `src\Directory.Build.props`, so normal `dotnet build`
 `.\build.ps1`, `.\run-app-local.ps1`, and CI builds all derive assembly metadata
 from the same tag history.
 
+## Tagged and untagged builds
+
+Tagged releases must resolve to the exact tag SemVer:
+
+- `vX.Y.Z` -> `X.Y.Z`
+- `vX.Y.Z-alpha.N` -> `X.Y.Z-alpha.N`
+
+Untagged `master` checkouts are still prerelease builds. After an alpha tag,
+GitVersion advances to the next alpha prerelease until another tag pins the
+version. For example, after `v0.6.0-alpha.5`, an untagged commit on `master`
+may resolve to `0.6.0-alpha.6`.
+
+`GitVersion.yml` intentionally gives the `master`/`main` branch the `alpha`
+label so alpha tags are treated as exact version sources. Do not remove that
+label unless the release train stops using alpha tags.
+
 ## Assembly metadata
 
 GitVersion-derived builds set:
@@ -46,6 +62,11 @@ value that could hide drift.
 Release build jobs must check out full git history (`fetch-depth: 0`) so
 GitVersion can see tags.
 
+Tagged CI runs verify that `github.ref_name` and GitVersion's `SemVer` output
+match before build artifacts are published. If a release tag is
+`v0.6.0-alpha.5`, CI must produce `0.6.0-alpha.5`; a derived value such as
+`0.6.0-alpha.6` or `0.6.0-712` is a release-blocking error.
+
 ## Local scripts
 
 `scripts\Get-OpenClawVersion.ps1` uses the repository-local
@@ -68,6 +89,8 @@ For example:
 - Do not hardcode user-visible version strings like `vX.Y.Z` in active code or
   tests; use `AppVersionInfo`.
 - Keep release tags and `GitVersion.yml` as the versioning contract.
+- Keep `GitVersion.yml` configured so exact alpha tags resolve to their tag
+  SemVer, and keep CI's tag/version verification enabled.
 
 ## References