fix(workflows): harden even/odd versioning against regression and syntax errors (#816)

## Description

Hardened the even/odd marketplace versioning convention across all
release workflows. Filtered `LAST_TAG` to stable-only (even-minor) tags
to prevent version regression when pre-release tags exist. Fixed a
corrupted jq `//` operator syntax in the manifest fallback. Added an
even-minor validation step after release-please to block odd-minor
stable releases. Added plugin generation to the prerelease workflow to
fix Plugin Validation CI failures.

## Related Issue(s)

Closes #815

## Type of Change

Select all that apply:

**Code & Documentation:**

* [x] Bug fix (non-breaking change fixing an issue)
* [ ] New feature (non-breaking change adding functionality)
* [ ] Breaking change (fix or feature causing existing functionality to
change)
* [ ] Documentation update

**Infrastructure & Configuration:**

* [x] GitHub Actions workflow
* [ ] Linting configuration (markdown, PowerShell, etc.)
* [ ] Security configuration
* [ ] DevContainer configuration
* [ ] Dependency update

**AI Artifacts:**

* [ ] Reviewed contribution with `prompt-builder` agent and addressed
all feedback
* [ ] Copilot instructions (`.github/instructions/*.instructions.md`)
* [ ] Copilot prompt (`.github/prompts/*.prompt.md`)
* [ ] Copilot agent (`.github/agents/*.agent.md`)
* [ ] Copilot skill (`.github/skills/*/SKILL.md`)

**Other:**

* [ ] Script/automation (`.ps1`, `.sh`, `.py`)
* [ ] Other (please describe):

## Testing

Validated YAML syntax on all 4 workflow files. Reviewed the even/odd
logic for correctness:

- `LAST_TAG` awk filter correctly selects even-minor tags via `$(NF-1) %
2 == 0`
- jq fallback `.["."] // "0.0.0"` is syntactically valid
- Even-minor guard uses `steps.release.outputs.minor` from
release-please
- Pre-release version format `{MAJOR}.{ODD_MINOR}.{COMMIT_COUNT}` avoids
SemVer suffixes incompatible with VS Code marketplace

## Checklist

### Required Checks

* [x] Documentation is updated (if applicable)
* [x] Files follow existing naming conventions
* [x] Changes are backwards compatible (if applicable)
* [ ] Tests added for new functionality (if applicable)

### AI Artifact Contributions

N/A

### Required Automated Checks

The following validation commands must pass before merging:

* [x] Markdown linting: `npm run lint:md`
* [x] Spell checking: `npm run spell-check`
* [x] Frontmatter validation: `npm run lint:frontmatter`
* [x] Skill structure validation: `npm run validate:skills`
* [x] Link validation: `npm run lint:md-links`
* [x] PowerShell analysis: `npm run lint:ps`

## Additional Notes

- This PR replaces the SemVer `-rc.N` pre-release suffix approach with
the VS Code marketplace even/odd minor convention (even = stable, odd =
pre-release).
- The `LAST_TAG` filter prevents version regression that would occur if
`git describe` picked up a pre-release (odd-minor) tag as the baseline
for computing the next version.
- PR #739 proposes `3.1.0` as a stable release, which conflicts with
even/odd convention. It should be closed after this PR merges.

Author: WilliamBerryiii

.github/workflows/extension-publish.yml

@@ -58,10 +58,11 @@ jobs:
             exit 1
           fi
 
-          # Validate stable version (must not contain pre-release suffix)
-          if echo "$VERSION" | grep -qE '\-rc\.[0-9]+'; then
-            echo "::error::Stable channel does not accept pre-release versions. Got: $VERSION"
-            echo "::error::Use extension-publish-prerelease workflow for -rc.N versions"
+          # Even/odd convention: even minor = stable, odd minor = pre-release
+          PUBLISH_MINOR=$(echo "$VERSION" | cut -d. -f2)
+          if (( PUBLISH_MINOR % 2 == 1 )); then
+            echo "::error::Stable channel requires even minor version. Got: $VERSION (odd minor = pre-release)"
+            echo "::error::Use the pre-release publish workflow for odd-minor versions"
             exit 1
           fi
 

.github/workflows/main.yml

@@ -122,6 +122,15 @@ jobs:
           # created in the next step, ensuring subsequent runs find it.
           skip-github-pull-request: ${{ github.event_name == 'push' && startsWith(github.event.head_commit.message, 'chore(main)') }}
 
+      - name: Validate even-minor convention
+        if: ${{ steps.release.outputs.release_created == 'true' }}
+        run: |
+          MINOR="${{ steps.release.outputs.minor }}"
+          if (( MINOR % 2 != 0 )); then
+            echo "::error::Release version ${{ steps.release.outputs.version }} has odd minor ($MINOR). Even/odd convention requires even minor for stable releases."
+            exit 1
+          fi
+
       # Workaround: release-please with "draft": true uses lazy tag
       # creation. The git tag is not materialized until the release is
       # published. Without the tag, release-please cannot find the draft
@@ -192,7 +201,7 @@ jobs:
             RELEASED="${{ needs.release-please.outputs.version }}"
             MAJOR=$(echo "$RELEASED" | cut -d. -f1)
             MINOR=$(echo "$RELEASED" | cut -d. -f2)
-            PRE_VERSION="${MAJOR}.$((MINOR + 1)).0-rc.0"
+            PRE_VERSION="${MAJOR}.$((MINOR + 1)).0"
             gh pr edit "$PR_NUMBER" \
               --title "chore(main): pre-release $PRE_VERSION" \
               --body "## Pre-Release $PRE_VERSION

.github/workflows/prerelease-release.yml

@@ -45,19 +45,20 @@ jobs:
           REPO: ${{ github.repository }}
           MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}
         run: |
-          VERSION=$(echo "$PR_TITLE" | grep -oE 'pre-release [0-9]+\.[0-9]+\.[0-9]+(-rc\.[0-9]+)?' | grep -oE '[0-9]+\.[0-9]+\.[0-9]+(-rc\.[0-9]+)?')
+          VERSION=$(echo "$PR_TITLE" | grep -oE 'pre-release [0-9]+\.[0-9]+\.[0-9]+' | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')
           if [ -z "$VERSION" ]; then
             echo "⚠️ Could not extract version from PR title, falling back to manifest"
-            VERSION=$(jq -r '.["."]//"0.0.0"' .release-please-manifest.json 2>/dev/null || echo "")
+            VERSION=$(jq -r '.["."] // "0.0.0"' .release-please-manifest.json 2>/dev/null || echo "")
           fi
           if [ -z "$VERSION" ]; then
             echo "::error::Could not extract version from PR title or manifest: $PR_TITLE"
             exit 1
           fi
 
-          # Validate pre-release version contains SemVer -rc suffix
-          if ! echo "$VERSION" | grep -qE '\-rc\.[0-9]+$'; then
-            echo "::error::Pre-release version $VERSION must contain an -rc.N suffix"
+          # Even/odd convention: pre-release versions must have odd minor
+          PRE_MINOR=$(echo "$VERSION" | cut -d. -f2)
+          if (( PRE_MINOR % 2 == 0 )); then
+            echo "::error::Pre-release version $VERSION must have an odd minor (even/odd convention)"
             exit 1
           fi
 

.github/workflows/prerelease.yml

@@ -45,45 +45,49 @@ jobs:
           CURRENT=$(jq -r '.["."]//"0.0.0"' .release-please-manifest.json)
           MAJOR=$(echo "$CURRENT" | cut -d. -f1)
           MINOR=$(echo "$CURRENT" | cut -d. -f2)
-          PATCH=$(echo "$CURRENT" | cut -d. -f3)
 
-          # Find the last release tag for commit range analysis
-          LAST_TAG=$(git describe --tags --abbrev=0 --match 'hve-core-v*' 2>/dev/null || echo "")
+          # Find the last stable release tag (even minor) for commit range analysis.
+          # Pre-release tags (odd minor) are excluded to prevent version regression
+          # when a pre-release tag exists between the last stable tag and HEAD.
+          LAST_TAG=$(git tag -l 'hve-core-v*' | awk -F'[v.]' '{if ($(NF-1) % 2 == 0) print}' | sort -V | tail -1)
 
-          # Check for breaking changes and new features since last release.
+          # Check for breaking changes since last release.
           # Match conventional commit subject with ! (e.g. feat!:) or
           # a BREAKING CHANGE / BREAKING-CHANGE footer token at line start.
           HAS_BREAKING=0
-          HAS_FEAT=0
           if [ -n "$LAST_TAG" ]; then
             HAS_BREAKING=$(git log "$LAST_TAG"..HEAD --format='%s%n%b' | \
               grep -cE '^[a-z]+(\(.+\))?!:|^BREAKING[ -]CHANGE:' || true)
-            HAS_FEAT=$(git log "$LAST_TAG"..HEAD --format='%s' | \
-              grep -cE '^feat(\(.+\))?[!]?:' || true)
           fi
 
-          # Compute base version using conventional commit bump rules
+          # Even/odd convention: odd minor = pre-release, even minor = stable.
+          # Compute the next odd minor from the current manifest version.
           if [ "$HAS_BREAKING" -gt 0 ]; then
-            BASE_VERSION="$((MAJOR + 1)).0.0"
-          elif [ "$HAS_FEAT" -gt 0 ]; then
-            BASE_VERSION="${MAJOR}.$((MINOR + 1)).0"
+            PRE_MAJOR=$((MAJOR + 1))
+            PRE_MINOR=1
           else
-            BASE_VERSION="${MAJOR}.${MINOR}.$((PATCH + 1))"
+            PRE_MAJOR=$MAJOR
+            if (( MINOR % 2 == 0 )); then
+              PRE_MINOR=$((MINOR + 1))
+            else
+              PRE_MINOR=$MINOR
+            fi
           fi
 
-          # Append SemVer pre-release suffix with commit count as rc number
-          RC_NUMBER=$(git rev-list --count "${LAST_TAG}..HEAD" 2>/dev/null || echo "1")
-          PRE_VERSION="${BASE_VERSION}-rc.${RC_NUMBER}"
+          # Use commit count since last tag as patch for unique, monotonic versions
+          COMMIT_COUNT=$(git rev-list --count "${LAST_TAG}..HEAD" 2>/dev/null || echo "0")
+          PRE_VERSION="${PRE_MAJOR}.${PRE_MINOR}.${COMMIT_COUNT}"
 
           echo "version=$PRE_VERSION" >> "$GITHUB_OUTPUT"
-          echo "Computed pre-release version: $PRE_VERSION (base: $BASE_VERSION, rc: $RC_NUMBER, current: $CURRENT)"
+          echo "last_tag=$LAST_TAG" >> "$GITHUB_OUTPUT"
+          echo "Computed pre-release version: $PRE_VERSION (current: $CURRENT, last stable: $LAST_TAG)"
 
       - name: Generate changelog
         id: changelog
         env:
           PRE_VERSION: ${{ steps.version.outputs.version }}
+          LAST_TAG: ${{ steps.version.outputs.last_tag }}
         run: |
-          LAST_TAG=$(git describe --tags --abbrev=0 --match 'hve-core-v*' 2>/dev/null || echo "")
           MAX_COUNT_ARG=""
           if [ -z "$LAST_TAG" ]; then
             RANGE="HEAD"
@@ -149,6 +153,22 @@ jobs:
             echo 'CHANGELOG_EOF'
           } >> "$GITHUB_OUTPUT"
 
+      - name: Setup Node.js
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v4.1.0
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install PowerShell-Yaml
+        shell: pwsh
+        run: |
+          if (-not (Get-Module -ListAvailable -Name PowerShell-Yaml)) {
+            Install-Module -Name PowerShell-Yaml -Force -Scope CurrentUser
+          }
+
       - name: Update prerelease/next branch with version files
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
@@ -202,6 +222,14 @@ jobs:
             fi
           done
 
+          # Update .release-please-manifest.json so release-please sees the
+          # odd-minor version when this PR merges to main
+          jq --arg v "$PRE_VERSION" '.["."] = $v' .release-please-manifest.json > tmp.json \
+            && mv tmp.json .release-please-manifest.json
+
+          # Regenerate plugin outputs so plugin-validation passes
+          npm run plugin:generate
+
           git add -A
           git commit -m "chore: bump pre-release version to ${PRE_VERSION}" || echo "No version changes to commit"
           git push origin "$BRANCH"