fix: release pipeline + 4-digit version support (v0.8.10) (#34)

* fix: replace bash 4+ associative arrays with bash 3-compatible helpers

check_structural_fitness() used `declare -A` and check_doc_inventory() used
`local -A`, both requiring bash 4+. Stock macOS ships bash 3.2, causing the
script to crash silently and skip check_unprocessed() and check_mode().

Replaced with string-based key=value helpers (_kv_get, _kv_set, _kv_keys)
and linear search helpers (_is_root_doc, _is_project_doc). Fixes 3
pre-existing test failures.

* fix: tighten version regex and add gist bridge comment

Version validation regex in update-check tightened from the loose
^[0-9]+\.[0-9.]+$ (accepted malformed versions like 1..2) to
^[0-9]+\.[0-9]+\.[0-9]+(\.[0-9]+)?$ (enforces exactly X.Y.Z or X.Y.Z.W),
matching the roadmap-audit pattern.

Added comment explaining the permanent gist bridge for pre-0.8.8.1 installs.

* test: add 4-digit version and update-check tests

16 new tests: semver 4-digit comparisons (5), regex validation for valid
and invalid versions (14), update-check upgrade detection with MICRO
versions (2). Fixed stale setup test expectations (2→3 default skills,
3→4 with --with-native). 45 tests, 0 failures.

* feat: auto-tag GitHub Action on VERSION change

Creates annotated git tags (vX.Y.Z.W) automatically when VERSION changes
on merge to main. Idempotent: skips if tag already exists. Validates
VERSION format before tagging. Uses default GITHUB_TOKEN with contents:write.

* docs: add versioning section to README, update roadmap example

README now defines MAJOR.MINOR.PATCH.MICRO semantics with examples.
Replaced stale gist-migration example in roadmap skill with generic example.

* chore: bump version and changelog (v0.8.10)

Author: kbitz

.github/workflows/auto-tag.yml

@@ -0,0 +1,40 @@
+name: Auto-tag on VERSION change
+
+on:
+  push:
+    branches: [main]
+    paths: [VERSION]
+
+permissions:
+  contents: write
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Read version and create tag
+        run: |
+          VERSION=$(cat VERSION | tr -d '[:space:]')
+
+          if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+(\.[0-9]+)?$'; then
+            echo "Invalid VERSION format: '$VERSION'"
+            exit 1
+          fi
+
+          TAG="v${VERSION}"
+
+          if git rev-parse "$TAG" >/dev/null 2>&1; then
+            echo "Tag $TAG already exists — skipping."
+            exit 0
+          fi
+
+          echo "Creating tag $TAG"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "$TAG" -m "Release ${VERSION}"
+          git push origin "$TAG"
+          echo "Tagged $TAG successfully."

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.8.10] - 2026-04-15
+
+### Added
+- GitHub Action (`auto-tag.yml`) to create git tags automatically when VERSION changes on merge to main. Idempotent: skips if tag already exists.
+- Update-check and 4-digit version tests in `test-update.sh`: semver comparisons, regex validation, upgrade detection with MICRO versions.
+- Versioning section in README defining MAJOR.MINOR.PATCH.MICRO semantics.
+
+### Changed
+- Version validation regex in `bin/update-check` tightened from `^[0-9]+\.[0-9.]+$` to `^[0-9]+\.[0-9]+\.[0-9]+(\.[0-9]+)?$`. Now rejects malformed versions (double dots, trailing dots, 5+ segments) while accepting X.Y.Z and X.Y.Z.W.
+
+### Fixed
+- Added gist bridge comment in `bin/update-check` documenting why the old gist URL (pre-0.8.8.1) must be kept alive as a permanent upgrade bridge.
+- `bin/roadmap-audit`: replaced bash 4+ associative arrays (`declare -A`, `local -A`) with bash 3-compatible helpers. The old code crashed on stock macOS (bash 3.2), silently skipping `check_unprocessed()` and `check_mode()`. Fixed 3 pre-existing test failures.
+- `scripts/test-update.sh`: updated setup test expectations from 2 to 3 default skills (full-review was added in v0.8.0 but test wasn't updated). Fixed 2 pre-existing test failures.
+
 ## [0.8.9.0] - 2026-04-14
 
 ### Changed

README.md

@@ -176,6 +176,19 @@ native_trigger_file: ".context/snapshot-trigger"
 
 - [Implementation Guide](docs/debug-infrastructure-guide.md) — How to add debug infrastructure to a new SwiftUI app
 
+## Versioning
+
+4-digit SemVer: `MAJOR.MINOR.PATCH.MICRO`
+
+| Segment | Meaning | Example |
+|---------|---------|---------|
+| MAJOR   | Breaking changes | 1.0.0 |
+| MINOR   | New features, new skills | 0.9.0 |
+| PATCH   | Bug fixes, behavior changes | 0.8.10 |
+| MICRO   | Doc-only, config-only, no behavior change | 0.8.9.0 |
+
+Source of truth: `VERSION` file. Tags created automatically on merge to main.
+
 ## License
 
 [MIT](LICENSE)

VERSION

@@ -1 +1 @@
-0.8.9.0
+0.8.10

bin/roadmap-audit

@@ -1013,16 +1013,22 @@ check_structural_fitness() {
   local section="none"
   local in_preflight=0
 
-  # Associative arrays for counting
-  declare -A group_task_counts
-  declare -A track_task_counts
+  # Bash 3-compatible key=value storage (no associative arrays)
+  # Format: "key1=val1 key2=val2 ..."
+  local group_task_counts=""
+  local track_task_counts=""
+
+  # Helpers: get/set/incr values in "key=val key=val" strings
+  _kv_get() { echo "$1" | tr ' ' '\n' | grep "^$2=" | tail -1 | cut -d= -f2; }
+  _kv_set() { echo "$1" | tr ' ' '\n' | grep -v "^$2=" | tr '\n' ' '; printf "%s=%s" "$2" "$3"; }
+  _kv_keys() { echo "$1" | tr ' ' '\n' | grep '=' | cut -d= -f1 | sort; }
 
   while IFS= read -r line; do
     # Group heading
     if echo "$line" | grep -qE '^## Group [0-9]+:'; then
       current_group=$(echo "$line" | sed -E 's/^## Group ([0-9]+):.*/\1/')
       group_count=$((group_count + 1))
-      group_task_counts[$current_group]=0
+      group_task_counts=$(_kv_set "$group_task_counts" "$current_group" 0)
       section="group"
       in_preflight=0
       current_track=""
@@ -1033,7 +1039,7 @@ check_structural_fitness() {
     if echo "$line" | grep -qE '^### Track [0-9]+[A-Z]:'; then
       current_track=$(echo "$line" | sed -E 's/^### Track ([0-9]+[A-Z]):.*/\1/')
       track_count=$((track_count + 1))
-      track_task_counts[$current_track]=0
+      track_task_counts=$(_kv_set "$track_task_counts" "$current_track" 0)
       section="track"
       in_preflight=0
       continue
@@ -1055,10 +1061,12 @@ check_structural_fitness() {
     if [ "$section" != "none" ] && echo "$line" | grep -qE '^- \*\*'; then
       task_count=$((task_count + 1))
       if [ -n "$current_group" ]; then
-        group_task_counts[$current_group]=$(( ${group_task_counts[$current_group]:-0} + 1 ))
+        local cur=$(_kv_get "$group_task_counts" "$current_group")
+        group_task_counts=$(_kv_set "$group_task_counts" "$current_group" $(( ${cur:-0} + 1 )))
       fi
       if [ "$in_preflight" -eq 0 ] && [ -n "$current_track" ]; then
-        track_task_counts[$current_track]=$(( ${track_task_counts[$current_track]:-0} + 1 ))
+        local cur=$(_kv_get "$track_task_counts" "$current_track")
+        track_task_counts=$(_kv_set "$track_task_counts" "$current_track" $(( ${cur:-0} + 1 )))
       fi
       continue
     fi
@@ -1067,7 +1075,8 @@ check_structural_fitness() {
     if [ "$in_preflight" -eq 1 ] && echo "$line" | grep -qE '^- [^*]'; then
       task_count=$((task_count + 1))
       if [ -n "$current_group" ]; then
-        group_task_counts[$current_group]=$(( ${group_task_counts[$current_group]:-0} + 1 ))
+        local cur=$(_kv_get "$group_task_counts" "$current_group")
+        group_task_counts=$(_kv_set "$group_task_counts" "$current_group" $(( ${cur:-0} + 1 )))
       fi
       continue
     fi
@@ -1082,18 +1091,20 @@ check_structural_fitness() {
   # Group sizes
   if [ "$group_count" -gt 0 ]; then
     local sizes=""
-    for g in $(echo "${!group_task_counts[@]}" | tr ' ' '\n' | sort -n); do
+    for g in $(_kv_keys "$group_task_counts"); do
+      local val=$(_kv_get "$group_task_counts" "$g")
       [ -n "$sizes" ] && sizes="${sizes},"
-      sizes="${sizes}${g}=${group_task_counts[$g]}"
+      sizes="${sizes}${g}=${val}"
     done
     echo "GROUP_SIZES: $sizes"
 
     # Track sizes
     if [ "$track_count" -gt 0 ]; then
       local tsizes=""
-      for t in $(echo "${!track_task_counts[@]}" | tr ' ' '\n' | sort); do
+      for t in $(_kv_keys "$track_task_counts"); do
+        local val=$(_kv_get "$track_task_counts" "$t")
         [ -n "$tsizes" ] && tsizes="${tsizes},"
-        tsizes="${tsizes}${t}=${track_task_counts[$t]}"
+        tsizes="${tsizes}${t}=${val}"
       done
       echo "TRACK_SIZES: $tsizes"
     fi
@@ -1102,13 +1113,12 @@ check_structural_fitness() {
     if [ "$group_count" -ge 2 ]; then
       local max_size=0
       local min_size=999999
-      for g in "${!group_task_counts[@]}"; do
-        local s=${group_task_counts[$g]}
+      for g in $(_kv_keys "$group_task_counts"); do
+        local s=$(_kv_get "$group_task_counts" "$g")
         [ "$s" -gt "$max_size" ] && max_size=$s
         [ "$s" -lt "$min_size" ] && min_size=$s
       done
       if [ "$min_size" -gt 0 ]; then
-        # Bash integer division with 2 decimal places
         local ratio_int=$((max_size * 100 / min_size))
         local ratio_whole=$((ratio_int / 100))
         local ratio_frac=$((ratio_int % 100))
@@ -1134,10 +1144,15 @@ check_doc_inventory() {
   local file_count=0
   local files_output=""
 
-  # Known doc types for labeling
-  local -A known_types=()
-  for doc in "${ROOT_DOCS[@]}"; do known_types["$doc"]="root doc"; done
-  for doc in "${DOCS_DIR_DOCS[@]}"; do known_types["$doc"]="project doc"; done
+  # Known doc types for labeling (bash 3 compatible)
+  _is_root_doc() {
+    for doc in "${ROOT_DOCS[@]}"; do [ "$doc" = "$1" ] && return 0; done
+    return 1
+  }
+  _is_project_doc() {
+    for doc in "${DOCS_DIR_DOCS[@]}"; do [ "$doc" = "$1" ] && return 0; done
+    return 1
+  }
 
   # Scan all .md files (including known ones, for inventory)
   while IFS= read -r filepath; do
@@ -1150,8 +1165,10 @@ check_doc_inventory() {
     todo_count=$(count_todo_patterns "$filepath")
 
     local doc_type="unknown"
-    if [ -n "${known_types[$basename]+x}" ]; then
-      doc_type="${known_types[$basename]}"
+    if _is_root_doc "$basename"; then
+      doc_type="root doc"
+    elif _is_project_doc "$basename"; then
+      doc_type="project doc"
     elif echo "$filepath" | grep -q '/docs/designs/' 2>/dev/null; then
       doc_type="design doc"
     elif echo "$filepath" | grep -q '/docs/archive/' 2>/dev/null; then

bin/update-check

@@ -19,6 +19,10 @@ MARKER_FILE="$STATE_DIR/just-upgraded-from"
 SNOOZE_FILE="$STATE_DIR/update-snoozed"
 VERSION_FILE="$EXTEND_DIR/VERSION"
 REMOTE_URL="${GSTACK_EXTEND_REMOTE_URL:-https://raw.githubusercontent.com/kbitz/gstack-extend/main/VERSION}"
+# NOTE: Pre-0.8.8.1 installs still check a gist at the old URL
+# (gist ID 511b8a4861f7b4df3a7fedd42911c701). That gist is kept as a
+# permanent bridge so those installs can discover the upgrade to this
+# raw GitHub URL. Do not delete the gist.
 
 # ─── Force flag (busts cache + snooze) ──────────────────────
 if [ "${1:-}" = "--force" ]; then
@@ -150,7 +154,7 @@ REMOTE="$(curl -sf --max-time 5 "$REMOTE_URL" 2>/dev/null || true)"
 REMOTE="$(echo "$REMOTE" | tr -d '[:space:]')"
 
 # Validate: must look like a version number (reject HTML error pages)
-if ! echo "$REMOTE" | grep -qE '^[0-9]+\.[0-9.]+$'; then
+if ! echo "$REMOTE" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+(\.[0-9]+)?$'; then
   # Invalid or empty response — assume up to date
   echo "UP_TO_DATE $LOCAL" > "$CACHE_FILE"
   exit 0

docs/PROGRESS.md

@@ -6,6 +6,7 @@ Build the /browse-native skill and validate it against real macOS apps.
 
 | Version | Date | Summary |
 |---------|------|---------|
+| 0.8.10 | 2026-04-15 | Release pipeline fix: tightened update-check version regex, auto-tag GitHub Action, 4-digit version tests, README versioning section (MICRO semantics), gist bridge comment. Fixed bash 3 crash in roadmap-audit (associative arrays), fixed stale setup test expectations. 128 tests, 0 failures. |
 | 0.8.9.0 | 2026-04-14 | Roadmap audit accepts 4-digit versions (X.Y.Z.W). MICRO segment for doc-only/config bumps. Removed stale design docs, trimmed CLAUDE.md, refreshed roadmap (Track 2A done, added Track 1B: Roadmap Onboarding). |
 | 0.8.8.1 | 2026-04-14 | Public-ready cleanup: MIT license, gist-to-raw-GitHub version check migration, removed archived design docs with internal references, anonymized app name across docs and skill, SSH→HTTPS clone URL. |
 | 0.8.8 | 2026-04-13 | /roadmap triage mode now runs the freshness scan (Step 3.5) before classifying items into groups. Previously, triage slotted new items into potentially-complete groups because the scan was gated to update mode only. Stale/completed tasks are now always cleaned before new items get placed. Early exit no longer skips the freshness check. |