feat: version-tagged releases with update check and workflow (issue #87)

Adds VERSION file (2.0.0), SessionStart version check that notifies
when a newer release is available, /devkit-sync update workflow for
controlled upgrades, and CHANGELOG.md v2.0.0 entry documenting all
changes in this release.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: HerbHall

CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## v2.0.0 -- 2026-02-25
+
+v2.0 represents a major architectural shift from a bash-centric toolkit to a
+cross-platform, multi-tier system with formal versioning.
+
+### Added
+
+- Three-tier settings architecture (ADR-0012): User > DevSpace > Project cascade
+- Dual-language scripting strategy (ADR-0013): PowerShell primary, bash legacy
+- Cross-platform path resolution via `~/.devkit-config.json`
+- Forge abstraction layer for GitHub/GitLab operations
+- Project registry for multi-project coordination
+- Local overrides via `.local.md` pattern (gitignored, machine-specific)
+- SessionStart hardening: rate limiting (1/hour), lock-file awareness, pull logging
+- Auto-push prompt after `/reflect` sessions
+- Version-tagged releases with `VERSION` file as single source of truth
+- SessionStart version check: notifies when a newer DevKit release is available
+- `devkit update` command via `/devkit-sync` skill (check version, upgrade to tag or latest)
+- `devkit promote` command for graduating local patterns to universal rules
+
+### Version Policy
+
+- MAJOR: Breaking changes to rules, skill interfaces, or sync protocol
+- MINOR: New skills, agents, or non-breaking rule additions
+- PATCH: Bug fixes, documentation, pattern additions
+
 ## v1.2.0 -- 2026-02-21
 
 ### Fixed

VERSION

@@ -1 +1 @@
-1.0.0
+2.0.0

claude/hooks/SessionStart.sh

@@ -100,6 +100,54 @@ devkit_pull() {
 
 devkit_pull
 
+# ===== Version Check =====
+# Compare local VERSION with origin/main after devkit_pull's fetch.
+# Only prints when a newer version is available (no noise otherwise).
+devkit_version_check() {
+    local devkit_path="$1"
+
+    # Nothing to check if no DevKit path or no VERSION file
+    if [ -z "$devkit_path" ] || [ ! -f "$devkit_path/VERSION" ]; then
+        return 0
+    fi
+
+    local current remote
+    current=$(cat "$devkit_path/VERSION" 2>/dev/null | tr -d '[:space:]')
+    remote=$(git -C "$devkit_path" show origin/main:VERSION 2>/dev/null | tr -d '[:space:]')
+
+    # Skip if either version is empty or they match
+    if [ -z "$current" ] || [ -z "$remote" ] || [ "$current" = "$remote" ]; then
+        return 0
+    fi
+
+    echo "DevKit: new version available (current: $current, latest: $remote)"
+}
+
+# Resolve devkit_path using the same logic as devkit_pull for the version check.
+# This duplicates path resolution but keeps devkit_pull's local scope intact.
+_devkit_resolve_path() {
+    local config="$HOME/.devkit-config.json"
+    if [ -f "$config" ]; then
+        local devspace
+        devspace=$(grep -o '"devspacePath"[[:space:]]*:[[:space:]]*"[^"]*"' "$config" | head -1 | sed 's/.*"devspacePath"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' | sed 's|\\\\|/|g')
+        if [ -z "$devspace" ]; then
+            devspace=$(grep -o '"devspace"[[:space:]]*:[[:space:]]*"[^"]*"' "$config" | head -1 | sed 's/.*"devspace"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' | sed 's|\\\\|/|g')
+        fi
+        if [ -n "$devspace" ] && [ -f "$devspace/devkit/.sync-manifest.json" ]; then
+            echo "$devspace/devkit"
+            return 0
+        fi
+    fi
+    for candidate in "$HOME/DevSpace/devkit" "$HOME/workspace/devkit" "$HOME/devkit"; do
+        if [ -f "$candidate/.sync-manifest.json" ]; then
+            echo "$candidate"
+            return 0
+        fi
+    done
+}
+
+devkit_version_check "$(_devkit_resolve_path)"
+
 # ===== CLAUDE.md Detection =====
 
 # Skip if we're in the home directory

claude/skills/devkit-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: devkit-sync
-description: Manual sync operations for DevKit multi-machine synchronization. Status, push, pull, init, diff, and unlink.
+description: Manual sync operations for DevKit multi-machine synchronization. Status, push, pull, init, diff, unlink, and update.
 user_invocable: true
 ---
 
@@ -28,6 +28,7 @@ What sync operation do you need?
 5. **Diff** -- Show detailed diff of local changes vs DevKit main
 6. **Unlink** -- Replace symlinks with copies (portable snapshot)
 7. **Resolve conflicts** -- Fix merge conflicts after pull/rebase
+8. **Update** -- Check version and upgrade to a specific release or latest
 
 Or just type your question about DevKit sync.
 </intake>
@@ -37,11 +38,12 @@ Or just type your question about DevKit sync.
 |----------|----------|
 | 1, "status", "state", "health", "check" | workflows/status.md |
 | 2, "push", "commit", "upload", "share" | workflows/push.md |
-| 3, "pull", "fetch", "update", "download" | workflows/pull.md |
+| 3, "pull", "fetch", "download" | workflows/pull.md |
 | 4, "init", "setup", "install", "link" | workflows/init.md |
 | 5, "diff", "changes", "what changed" | workflows/diff.md |
 | 6, "unlink", "copy", "snapshot", "portable" | workflows/unlink.md |
 | 7, "resolve", "conflicts", "conflict", "merge conflict", "rebase conflict" | workflows/resolve-conflicts.md |
+| 8, "update", "upgrade", "version", "release" | workflows/update.md |
 
 **After reading the workflow, follow it exactly.**
 </routing>

claude/skills/devkit-sync/workflows/update.md

@@ -0,0 +1,70 @@
+# DevKit Sync: Update
+
+Check current version and upgrade to a specific release or latest.
+
+## Steps
+
+1. **Resolve DevKit path** from config or common locations.
+
+2. **Read current version:**
+
+   ```bash
+   cat <devkit>/VERSION
+   ```
+
+   Report: "Current version: X.Y.Z"
+
+3. **Fetch latest tags from origin:**
+
+   ```bash
+   git -C <devkit> fetch origin --tags
+   ```
+
+4. **Show available versions** (most recent first):
+
+   ```bash
+   git -C <devkit> tag -l "v*" --sort=-v:refname | head -5
+   ```
+
+   If no tags exist: "No tagged releases found. Use `/devkit-sync pull` to track main HEAD."
+
+5. **Determine target version:**
+   - If user said `--latest` or "latest": target is `main` HEAD
+   - If user specified a version (e.g., `v2.0.0`): target is that tag
+   - Otherwise: target is the newest tag from step 4
+
+6. **Check for local changes** that would block checkout:
+
+   ```bash
+   git -C <devkit> status --porcelain
+   ```
+
+   If dirty: warn and offer to stash first.
+
+7. **Apply the update:**
+   - For a tag target:
+
+     ```bash
+     git -C <devkit> checkout <tag>
+     ```
+
+   - For latest (main HEAD):
+
+     ```bash
+     git -C <devkit> pull --rebase origin main
+     ```
+
+8. **Confirm version change:**
+
+   ```bash
+   cat <devkit>/VERSION
+   ```
+
+   Report: "Updated from X.Y.Z to A.B.C. Symlinked files updated instantly."
+
+## Edge Cases
+
+- Network unavailable: report fetch failure, show current version
+- No VERSION file: report "VERSION file not found -- this DevKit predates version tagging"
+- Target tag not found: list available tags, ask user to pick one
+- Dirty working tree: offer stash/unstash flow