Add "lessons/sprints/versioning-workflow---use-unreleased-and-release-script"

lessons%2Fsprints%2Fversioning-workflow---use-unreleased-and-release-script.-.md

@@ -0,0 +1,47 @@
+## Context
+
+Version drift was discovered where CHANGELOG.md had a `[3.1.2]` entry dated 2026-01-23, but no git tag existed. The marketplace.json was also out of sync.
+
+## Problem
+
+The root cause was documenting changes under a versioned CHANGELOG section (`[3.1.2]`) before the release process was complete. This violates the Keep a Changelog standard where:
+
+1. All work-in-progress goes under `[Unreleased]`
+2. Versioned sections are only created at release time
+3. Version must be consistent across: git tags, README, marketplace.json, CHANGELOG
+
+## Solution
+
+Created a standardized versioning workflow:
+
+1. **During development:** All changes go under `[Unreleased]` in CHANGELOG.md
+2. **At release time:** Use `./scripts/release.sh X.Y.Z` which:
+   - Validates `[Unreleased]` has content
+   - Renames `[Unreleased]` to `[X.Y.Z] - YYYY-MM-DD`
+   - Updates README.md title
+   - Updates marketplace.json version
+   - Commits and creates git tag
+
+3. **Documentation:** CLAUDE.md now includes versioning workflow with:
+   - Version locations table
+   - SemVer guidelines (PATCH/MINOR/MAJOR)
+   - Development vs release workflows
+
+## Prevention
+
+1. **Never create versioned CHANGELOG sections manually** - always use `[Unreleased]`
+2. **Use the release script** - ensures atomic, consistent updates
+3. **SemVer discipline:**
+   - PATCH (x.y.Z): bug fixes only
+   - MINOR (x.Y.0): new features
+   - MAJOR (X.0.0): breaking changes
+
+## Related
+
+- Issue: #143
+- Branch: `fix/issue-143-versioning-workflow`
+- Release: v3.2.0
+- Files: `scripts/release.sh`, CLAUDE.md, CHANGELOG.md
+
+---
+**Tags:** versioning, semver, changelog, release, workflow, documentation