Enforce POLICY-RELEASE-001: align git tag with SKILL.md and SKILL_VERSION

release.ps1

@@ -7,6 +7,10 @@
   Encryption, ZIP packaging, and marketplace sync are done by CI
   (.github/workflows/release_skill.yaml → reusable-release-skill.yaml@main).
 
+  POLICY-RELEASE-001: before tagging, requires SKILL.md version and
+  scripts/util/constants.py SKILL_VERSION to equal the next tag (without prefix).
+  release.ps1 does not auto-edit those fields.
+
   Requires: git, PowerShell 5+
 
   After fetch, runs default tests against the current working tree (before auto-commit):
@@ -162,6 +166,93 @@ function Get-NextTag {
   return "$TagPrefix$($latest.Major).$($latest.Minor).$([int]$latest.Patch + 1)"
 }
 
+function Read-SkillMdVersion {
+  param([Parameter(Mandatory = $true)][string]$SkillRoot)
+
+  $path = Join-Path $SkillRoot "SKILL.md"
+  if (-not (Test-Path -LiteralPath $path)) {
+    return $null
+  }
+  $text = Get-Content -LiteralPath $path -Raw -Encoding UTF8 -ErrorAction SilentlyContinue
+  if ([string]::IsNullOrWhiteSpace($text)) {
+    return $null
+  }
+  $m = [regex]::Match($text, '(?m)^version:\s*["'']?([0-9]+\.[0-9]+\.[0-9]+)["'']?\s*$')
+  if (-not $m.Success) {
+    return $null
+  }
+  return $m.Groups[1].Value.Trim()
+}
+
+function Read-SkillConstantsVersion {
+  param([Parameter(Mandatory = $true)][string]$SkillRoot)
+
+  $path = Join-Path $SkillRoot "scripts\util\constants.py"
+  if (-not (Test-Path -LiteralPath $path)) {
+    return $null
+  }
+  $text = Get-Content -LiteralPath $path -Raw -Encoding UTF8 -ErrorAction SilentlyContinue
+  if ([string]::IsNullOrWhiteSpace($text)) {
+    return $null
+  }
+  $m = [regex]::Match($text, '(?m)^SKILL_VERSION\s*=\s*["'']([0-9]+\.[0-9]+\.[0-9]+)["'']')
+  if (-not $m.Success) {
+    return $null
+  }
+  return $m.Groups[1].Value.Trim()
+}
+
+# POLICY-RELEASE-001: marketplace latest (git tag) must equal package manifest versions.
+function Assert-SkillReleaseVersionAlignment {
+  param(
+    [Parameter(Mandatory = $true)][string]$SkillRoot,
+    [Parameter(Mandatory = $true)][string]$NextTag,
+    [Parameter(Mandatory = $true)][string]$TagPrefix
+  )
+
+  $skillMdPath = Join-Path $SkillRoot "SKILL.md"
+  if (-not (Test-Path -LiteralPath $skillMdPath)) {
+    return
+  }
+
+  $expected = $NextTag
+  if ($TagPrefix -and $expected.StartsWith($TagPrefix)) {
+    $expected = $expected.Substring($TagPrefix.Length)
+  }
+  $expected = $expected.Trim()
+  if ($expected -notmatch '^\d+\.\d+\.\d+$') {
+    throw "Release check failed (POLICY-RELEASE-001): cannot derive semver from Next tag '$NextTag'."
+  }
+
+  $mdVersion = Read-SkillMdVersion -SkillRoot $SkillRoot
+  $constVersion = Read-SkillConstantsVersion -SkillRoot $SkillRoot
+
+  $problems = @()
+  if ([string]::IsNullOrWhiteSpace($mdVersion)) {
+    $problems += "SKILL.md missing top-level version: X.Y.Z"
+  }
+  elseif ($mdVersion -ne $expected) {
+    $problems += "SKILL.md version=$mdVersion (want $expected)"
+  }
+  if ([string]::IsNullOrWhiteSpace($constVersion)) {
+    $problems += "scripts/util/constants.py missing SKILL_VERSION = `"X.Y.Z`""
+  }
+  elseif ($constVersion -ne $expected) {
+    $problems += "SKILL_VERSION=$constVersion (want $expected)"
+  }
+
+  if ($problems.Count -gt 0) {
+    throw (
+      "Release aborted (POLICY-RELEASE-001): Next tag=$NextTag requires manifest version $expected, but " +
+      ($problems -join "; ") +
+      ". Bump SKILL.md version and scripts/util/constants.py SKILL_VERSION to $expected (and CHANGELOG), then re-run release.ps1. " +
+      "release.ps1 does not auto-edit these fields."
+    )
+  }
+
+  Write-Host "Version alignment OK: tag=$NextTag == SKILL.md=$mdVersion == SKILL_VERSION=$constVersion" -ForegroundColor DarkGray
+}
+
 function Assert-SkillReleasePackagingSources {
   param([Parameter(Mandatory = $true)][string]$SkillRoot)
 
@@ -283,6 +374,15 @@ try {
     Assert-SkillReleasePackagingSources -SkillRoot $skillRoot
   }
 
+  $nextTag = Get-NextTag -TagPrefix $Prefix
+  Write-Host "Next tag: $nextTag" -ForegroundColor Green
+  Assert-SkillReleaseVersionAlignment -SkillRoot $skillRoot -NextTag $nextTag -TagPrefix $Prefix
+
+  $existing = @(Get-GitOutput -GitArgs @("tag", "--list", $nextTag))
+  if ($existing.Length -gt 0) {
+    throw "Tag already exists: $nextTag"
+  }
+
   Invoke-DefaultTests -SkillRoot $skillRoot -Skip:$SkipTests
 
   Ensure-CleanOrAutoCommit -DoAutoCommit:$AutoCommit -NeedClean:$RequireClean -IsDryRun:$DryRun -Msg $CommitMessage
@@ -304,14 +404,6 @@ try {
     }
   }
 
-  $nextTag = Get-NextTag -TagPrefix $Prefix
-  Write-Host "Next tag: $nextTag" -ForegroundColor Green
-
-  $existing = @(Get-GitOutput -GitArgs @("tag", "--list", $nextTag))
-  if ($existing.Length -gt 0) {
-    throw "Tag already exists: $nextTag"
-  }
-
   if ($DryRun) {
     Write-Host "[DryRun] Would run: git tag -a $nextTag -F <utf8-msg-file> ($Message)" -ForegroundColor Yellow
     Write-Host "[DryRun] Would run: git push origin $nextTag" -ForegroundColor Yellow