bigpowers 2.73.5 → 2.73.7

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.73.5",
+  "version": "2.73.7",
   "description": "75 skills — 73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "keywords": [
     "pi-package"

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.73.7](https://github.com/danielvm-git/bigpowers/compare/v2.73.6...v2.73.7) (2026-07-07)
+
+
+### Bug Fixes
+
+* **migrate-spec:** split migrate-version.sh into lib modules under 300-line cap ([#62](https://github.com/danielvm-git/bigpowers/issues/62)) ([11842f2](https://github.com/danielvm-git/bigpowers/commit/11842f297c58d88df24f451316153242e3f4c63a))
+
+## [2.73.6](https://github.com/danielvm-git/bigpowers/compare/v2.73.5...v2.73.6) (2026-07-06)
+
+
+### Bug Fixes
+
+* **plan-release:** encapsulate G28 boolean logic in check-spec-version-gap ([#61](https://github.com/danielvm-git/bigpowers/issues/61)) ([613e45c](https://github.com/danielvm-git/bigpowers/commit/613e45c00a636f66783a220f35ec4e26916649ee))
+
 ## [2.73.5](https://github.com/danielvm-git/bigpowers/compare/v2.73.4...v2.73.5) (2026-07-06)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.73.5",
+  "version": "2.73.7",
   "description": "73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "main": "index.js",
   "scripts": {

package/scripts/check-spec-version-gap.sh

@@ -62,6 +62,35 @@ version_lt() {
   return 1
 }
 
+is_protected_branch() {
+  [[ "$1" == "main" || "$1" == "master" ]]
+}
+
+on_feature_branch() {
+  local branch="$1"
+  [[ -n "$branch" ]] || return 1
+  is_protected_branch "$branch" && return 1
+  return 0
+}
+
+yaml_value_set() {
+  local value="$1"
+  [[ -n "$value" ]] || return 1
+  [[ "$value" == "null" || "$value" == "None" ]] && return 1
+  return 0
+}
+
+has_dirty_specs() {
+  [[ -d "$SPECS" ]] && git -C "$PROJECT_DIR" status --porcelain -- specs/ 2>/dev/null | grep -q .
+}
+
+is_blocking_active_flow() {
+  local flow="$1"
+  yaml_value_set "$flow" || return 1
+  case "$flow" in build_epic|develop_tdd|fix_bug) return 0 ;; esac
+  return 1
+}
+
 find_migrations() {
   local ver="$1" reg="$BP_ROOT/specs/migrations/registry.okf.md"
   [[ ! -f "$reg" ]] && { echo "[]"; return; }
@@ -83,13 +112,12 @@ print(json.dumps(out))
 }
 
 check_active_work() {
-  local branch; branch=$(git -C "$PROJECT_DIR" branch --show-current 2>/dev/null || echo "")
-  if [[ -n "$branch" && "$branch" != "main" && "$branch" != "master" ]]; then echo "true"; return; fi
-  if [[ -d "$SPECS" ]] && git -C "$PROJECT_DIR" status --porcelain -- specs/ 2>/dev/null | grep -q .; then echo "true"; return; fi
-  local af; af=$(yaml_get "$SPECS/state.yaml" "active_flow")
-  if [[ -n "$af" && "$af" != "null" && "$af" != "None" ]]; then
-    case "$af" in build_epic|develop_tdd|fix_bug) echo "true"; return ;; esac
-  fi
+  local branch af
+  branch=$(git -C "$PROJECT_DIR" branch --show-current 2>/dev/null || echo "")
+  if on_feature_branch "$branch"; then echo "true"; return; fi
+  if has_dirty_specs; then echo "true"; return; fi
+  af=$(yaml_get "$SPECS/state.yaml" "active_flow")
+  if is_blocking_active_flow "$af"; then echo "true"; return; fi
   echo "false"
 }
 
@@ -103,7 +131,7 @@ fi
 
 SV=$(yaml_get "$SPECS/state.yaml" "bigpowers_version")
 
-if [[ -n "$SV" && "$SV" != "null" && "$SV" != "None" ]]; then
+if yaml_value_set "$SV"; then
   if [[ "$SV" == "$IV" ]]; then
     emit_json '{"gap":false,"stamp":true,"detected_version":"'"$SV"'","installed_version":"'"$IV"'","detection_method":"stamp","confidence":"high"}'
     exit 0
@@ -123,7 +151,7 @@ for f in release-plan.yaml execution-status.yaml product/SCOPE_LATEST.yaml metri
 done
 if [[ -f "$SPECS/state.yaml" ]]; then
   ec=$(yaml_get "$SPECS/state.yaml" "epic_cycle.current_step")
-  if [[ -n "$ec" && "$ec" != "null" && "$ec" != "None" ]]; then
+  if yaml_value_set "$ec"; then
     MARKERS+=("epic_cycle"); [[ "$DV" == "2.0.0" ]] && DV="2.20.0"
   fi
 fi

package/scripts/lib/migrate-version-common.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# story: e44s03 e44s04
+# Shared helpers for migrate-version.sh
+
+if [ -n "${MIGRATE_VERSION_COMMON_LOADED:-}" ]; then return 0; fi
+MIGRATE_VERSION_COMMON_LOADED=1
+
+migrate_usage() {
+  cat <<'EOF'
+Usage: scripts/migrate-version.sh [flags]
+
+Flags:
+  --help         Show this message
+  --dry-run      Compose migration plan and show diff, but make no changes
+  --force        Skip active-work block detection
+  --no-commit    Skip auto-commit (still applies transforms and stamps)
+  --verbose      Show detailed progress for each transform step
+  --project <dir>  Target project directory (migrations from bigpowers)
+EOF
+  exit 0
+}
+
+migrate_installed_version() {
+  node -e "console.log(require('$BIGPOWERS_ROOT/package.json').version)" 2>/dev/null || echo "unknown"
+}
+
+migrate_yaml_get() {
+  local file="$1" key="$2"
+  $PYTHON -c "
+import yaml, sys
+try:
+    d = yaml.safe_load(open('$file'))
+    val = d
+    for k in '$key'.split('.'):
+        if not isinstance(val, dict): sys.exit(1)
+        val = val.get(k)
+    if val is None: sys.exit(1)
+    print(val)
+except: sys.exit(1)
+" 2>/dev/null
+}
+
+log_info()  { echo "  [INFO] $*"; }
+log_warn()  { echo "  [WARN] $*"; }
+log_done()  { echo "  [OK] $*"; }
+log_fail()  { echo "  [FAIL] $*"; }
+log_skip()  { echo "  [SKIP] $*"; }
+
+migrate_yaml_value_set() {
+  local value="$1"
+  [[ -n "$value" ]] || return 1
+  [[ "$value" == "null" ]] && return 1
+  return 0
+}
+
+migrate_on_feature_branch() {
+  local branch="$1"
+  [[ -n "$branch" ]] || return 1
+  [[ "$branch" == "main" || "$branch" == "master" ]] && return 1
+  return 0
+}
+
+migrate_specs_clean() {
+  git -C "$REPO_ROOT" diff --quiet -- specs/ 2>/dev/null \
+    && git -C "$REPO_ROOT" diff --cached --quiet -- specs/ 2>/dev/null
+}
+
+migrate_preflight_block() {
+  local branch af
+  branch="$(git -C "$REPO_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null)" || true
+  if migrate_on_feature_branch "${branch:-}"; then
+    echo "migrate-version: BLOCKED — on non-main branch '$branch'. Use --force to override." >&2
+    return 3
+  fi
+  if ! migrate_specs_clean; then
+    echo "migrate-version: BLOCKED — uncommitted changes in specs/. Commit or stash first." >&2
+    return 3
+  fi
+  if [[ -f "$SPECS_DIR/state.yaml" ]]; then
+    af="$(migrate_yaml_get "$SPECS_DIR/state.yaml" "active_flow" 2>/dev/null)" || true
+    if migrate_yaml_value_set "${af:-}"; then
+      echo "migrate-version: BLOCKED — active_flow '$af' is set (mid-epic work). Use --force." >&2
+      return 3
+    fi
+  fi
+  return 0
+}
+
+migrate_detect_version() {
+  local stamped
+  DETECTED=""
+  if [[ -f "$SPECS_DIR/state.yaml" ]]; then
+    stamped="$(migrate_yaml_get "$SPECS_DIR/state.yaml" "bigpowers_version" 2>/dev/null)" || true
+    if migrate_yaml_value_set "${stamped:-}"; then
+      DETECTED="$stamped"
+    fi
+  fi
+  if [[ -z "$DETECTED" ]]; then
+    if [[ -f "$SPECS_DIR/STATE.md" && ! -f "$SPECS_DIR/state.yaml" ]]; then
+      DETECTED="1.0.0"
+    elif [[ -f "$SPECS_DIR/state.yaml" ]]; then
+      if migrate_yaml_get "$SPECS_DIR/state.yaml" "epic_cycle" >/dev/null 2>&1; then
+        DETECTED="2.20.0"
+      else
+        DETECTED="2.0.0"
+      fi
+    else
+      echo "migrate-version: cannot determine spec version" >&2
+      return 4
+    fi
+  fi
+  return 0
+}

package/scripts/lib/migrate-version-execute.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# story: e44s03
+# Migration execution loop for migrate-version.sh
+
+if [ -n "${MIGRATE_VERSION_EXECUTE_LOADED:-}" ]; then return 0; fi
+MIGRATE_VERSION_EXECUTE_LOADED=1
+
+migrate_execute_migrations() {
+  local MIG_LIST mig_json MIG_ID MIG_FILE MIG_TITLE BUNDLE_PATH TRANSFORMS T_LIST tjson action VERIFY_CMDS VERIFY_OK vcmd
+
+  echo ""
+  echo "Applying migrations …"
+  SUCCEEDED=()
+  FAILED=()
+  SKIPPED=()
+  SUCCEEDED_COUNT=0
+  FAILED_COUNT=0
+  SKIPPED_COUNT=0
+  UNCERTAINTY_COUNT=0
+
+  MIG_LIST="$(echo "$MIGRATION_PLAN" | $PYTHON -c "import json,sys; [print(json.dumps(m)) for m in json.load(sys.stdin)]")"
+  while IFS= read -r mig_json; do
+    [ -z "$mig_json" ] && continue
+    MIG_ID="$(echo "$mig_json" | $PYTHON -c "import json,sys; print(json.load(sys.stdin)['id'])")"
+    MIG_FILE="$(echo "$mig_json" | $PYTHON -c "import json,sys; print(json.load(sys.stdin)['file'])")"
+    MIG_TITLE="$(echo "$mig_json" | $PYTHON -c "import json,sys; print(json.load(sys.stdin)['title'])")"
+
+    BUNDLE_PATH="$MIGRATIONS_DIR/$MIG_FILE"
+    if [ ! -f "$BUNDLE_PATH" ]; then
+      log_warn "$MIG_ID: bundle file not found — skipping"
+      SKIPPED+=("$MIG_ID:bundle_missing")
+      continue
+    fi
+
+    echo ""
+    echo "── $MIG_ID: $MIG_TITLE ──"
+
+    TRANSFORMS="$($PYTHON -c "
+import yaml, json
+with open('$BUNDLE_PATH') as f:
+    parts = f.read().split('---')
+    fm = yaml.safe_load(parts[1])
+print(json.dumps(fm.get('transforms', []), default=str))
+" 2>/dev/null)"
+
+    T_LIST="$(echo "$TRANSFORMS" | $PYTHON -c "import json,sys; [print(json.dumps(t, default=str)) for t in json.load(sys.stdin)]")"
+    while IFS= read -r tjson; do
+      [ -z "$tjson" ] && continue
+      action="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('action',''))")"
+      apply_transform "$MIG_ID" "$action" "$tjson"
+    done <<< "$T_LIST"
+
+    VERIFY_CMDS="$($PYTHON -c "
+import yaml, json
+with open('$BUNDLE_PATH') as f:
+    parts = f.read().split('---')
+    fm = yaml.safe_load(parts[1])
+for a in fm.get('actions_needed', []):
+    v = a.get('verify', '')
+    if v: print(v)
+" 2>/dev/null)"
+
+    VERIFY_OK=true
+    while IFS= read -r vcmd; do
+      [ -z "$vcmd" ] && continue
+      log_info "verify: $vcmd"
+      if eval "$vcmd" 2>&1; then
+        log_done "verify passed"
+      else
+        log_fail "verify failed"
+        VERIFY_OK=false
+      fi
+    done <<< "$VERIFY_CMDS"
+
+    if [ "$VERIFY_OK" = "true" ]; then
+      SUCCEEDED+=("$MIG_ID")
+    else
+      FAILED+=("$MIG_ID")
+    fi
+  done <<< "$MIG_LIST"
+}

package/scripts/lib/migrate-version-plan.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# story: e44s03
+# Migration plan builder and dry-run preview for migrate-version.sh
+
+if [ -n "${MIGRATE_VERSION_PLAN_LOADED:-}" ]; then return 0; fi
+MIGRATE_VERSION_PLAN_LOADED=1
+
+migrate_build_plan() {
+  echo "migrate-version: building migration plan from $REGISTRY …"
+
+  MIGRATION_PLAN="$($PYTHON -c "
+import yaml, json, sys
+
+with open('$REGISTRY') as f:
+    parts = f.read().split('---')
+    fm = yaml.safe_load(parts[1])
+
+detected = '$DETECTED'
+installed = '$INSTALLED'
+
+plan = []
+for m in sorted(fm.get('migrations', []), key=lambda x: x.get('order', 99)):
+    sid = m['id']
+    since = m.get('since_version', '0')
+    order = m.get('order', 99)
+    deps = m.get('depends_on', [])
+    plan.append({'id': sid, 'file': m.get('file', sid + '.okf.md'),
+                 'since_version': since, 'order': order,
+                 'depends_on': deps, 'title': m.get('title', sid)})
+
+applicable = [m for m in plan if m['since_version'] > detected and m['since_version'] <= installed]
+print(json.dumps(applicable))
+" 2>/dev/null)"
+
+  MIGRATION_COUNT="$(echo "$MIGRATION_PLAN" | $PYTHON -c "import json,sys; print(len(json.load(sys.stdin)))" 2>/dev/null)"
+
+  if [ "${MIGRATION_COUNT:-0}" -eq 0 ]; then
+    echo "migrate-version: no applicable migrations for $DETECTED → $INSTALLED — stamping version only"
+  fi
+
+  echo "migrate-version: $MIGRATION_COUNT migration(s) to apply"
+
+  if [ "$VERBOSE" = "true" ]; then
+    echo "$MIGRATION_PLAN" | $PYTHON -c "
+import json,sys
+for m in json.load(sys.stdin):
+    print(f\"  {m['order']}. {m['id']}: {m['title']} (since {m['since_version']})\")
+"
+  fi
+}
+
+migrate_backup_specs() {
+  log_info "Creating backup: $BACKUP_DIR"
+  rm -rf "$BACKUP_DIR"
+  mkdir -p "$BACKUP_DIR"
+  cp -r "$SPECS_DIR"/* "$BACKUP_DIR"/ 2>/dev/null || true
+  rm -rf "$BACKUP_DIR/.pre-upgrade-backup" 2>/dev/null || true
+}
+
+migrate_print_dry_run() {
+  echo ""
+  echo "=========================================="
+  echo "  DRY RUN — no changes will be made"
+  echo "=========================================="
+  echo ""
+  echo "Detected version: $DETECTED"
+  echo "Target version:   $INSTALLED"
+  echo "Migrations:"
+  echo "$MIGRATION_PLAN" | $PYTHON -c "
+import json,sys
+for m in json.load(sys.stdin):
+    deps = m.get('depends_on', [])
+    dep_str = ' (depends on: ' + ', '.join(deps) + ')' if deps else ''
+    print(f\"  [{m['order']}] {m['id']}: {m['title']}{dep_str}\")
+"
+
+  echo ""
+  echo "Transforms preview:"
+  echo "$MIGRATION_PLAN" | $PYTHON -c "
+import json, sys, os
+for m in json.load(sys.stdin):
+    bundle_path = os.path.join('$MIGRATIONS_DIR', m['file'])
+    if not os.path.exists(bundle_path):
+        print(f\"  WARN {m['id']}: bundle file not found ({m['file']})\")
+        continue
+    with open(bundle_path) as f:
+        parts = f.read().split('---')
+        fm = __import__('yaml').safe_load(parts[1])
+    transforms = fm.get('transforms', [])
+    print(f\"\n  -- {m['id']}: {m['title']} --\")
+    for t in transforms:
+        action = t.get('action', '?')
+        note = t.get('note', '')
+        note_str = f' ({note})' if note else ''
+        if action == 'convert_md_to_yaml':
+            src = t.get('source', '?')
+            tgt = t.get('target', '?')
+            unc = t.get('uncertainty', [])
+            print(f\"  {action}: {src} -> {tgt}{note_str}\")
+            for u in unc:
+                print(f\"    GUESS: {u.get('field','?')} - {u.get('reason','?')}\")
+        elif action in ('rename_file', 'move_file'):
+            print(f\"  {action}: {t.get('source','?')} -> {t.get('target','?')}{note_str}\")
+        elif action == 'delete_file':
+            print(f\"  {action}: {t.get('path','?')}{note_str}\")
+        elif action in ('set_yaml_key', 'rename_yaml_key', 'delete_yaml_key'):
+            print(f\"  {action}: {t.get('file','?')} {t.get('key','?') or t.get('old_key','?')} = {t.get('value','?')}{note_str}\")
+        elif action == 'create_file_from_template':
+            print(f\"  {action}: {t.get('source','?')} -> {t.get('target','?')}{note_str}\")
+        else:
+            print(f\"  {action}{note_str}\")
+    for a in fm.get('actions_needed', []):
+        v = a.get('verify', '')
+        if v: print(f\"  verify: {v}\")
+" 2>/dev/null
+
+  echo ""
+  echo "Run without --dry-run to apply these migrations."
+}

package/scripts/lib/migrate-version-post.sh

@@ -0,0 +1,170 @@
+#!/usr/bin/env bash
+# story: e44s03 e44s04
+# Post-migration stamp, gates, report, and commit for migrate-version.sh
+
+if [ -n "${MIGRATE_VERSION_POST_LOADED:-}" ]; then return 0; fi
+MIGRATE_VERSION_POST_LOADED=1
+
+migrate_stamp_version() {
+  if [ -f "$SPECS_DIR/state.yaml" ]; then
+    log_info "Stamping bigpowers_version=$INSTALLED in state.yaml"
+    $PYTHON "$YAML_TOOLS" set "$SPECS_DIR/state.yaml" "bigpowers_version" "$INSTALLED"
+    log_done "stamp applied"
+  fi
+}
+
+migrate_run_soft_gates() {
+  if [ -f "$SCRIPT_DIR/validate-okf.sh" ]; then
+    log_info "Running validate-okf.sh (soft gate) …"
+    if bash "$SCRIPT_DIR/validate-okf.sh" --dir "$MIGRATIONS_DIR" 2>&1; then
+      log_done "validate-okf: PASS"
+    else
+      log_warn "validate-okf: some checks failed (soft gate — non-blocking)"
+    fi
+  else
+    log_info "validate-okf.sh not found — skipping soft gate"
+  fi
+
+  if [ -f "$SCRIPT_DIR/validate-specs-yaml.sh" ]; then
+    log_info "Running global validate-specs-yaml.sh …"
+    if bash "$SCRIPT_DIR/validate-specs-yaml.sh" 2>&1; then
+      log_done "validate-specs-yaml: PASS"
+    else
+      log_fail "validate-specs-yaml: FAIL"
+      FAILED+=("validate-specs-yaml")
+    fi
+  fi
+}
+
+migrate_check_staleness() {
+  local proj_lines bp_lines delta
+  STALE_FILES=()
+  BIGPOWERS_CLAUDE="$SCRIPT_DIR/../CLAUDE.md"
+  if [ -f "$REPO_ROOT/CLAUDE.md" ] && [ -f "$BIGPOWERS_CLAUDE" ]; then
+    proj_lines="$(wc -l < "$REPO_ROOT/CLAUDE.md")"
+    bp_lines="$(wc -l < "$BIGPOWERS_CLAUDE")"
+    delta=$((bp_lines - proj_lines))
+    if [ $delta -gt 20 ]; then
+      STALE_FILES+=("CLAUDE.md")
+      log_warn "CLAUDE.md: $delta lines behind bigpowers template — consider updating"
+    fi
+  fi
+  if [ -f "$REPO_ROOT/CONVENTIONS.md" ] && [ -f "$SCRIPT_DIR/../CONVENTIONS.md" ]; then
+    proj_lines="$(wc -l < "$REPO_ROOT/CONVENTIONS.md")"
+    bp_lines="$(wc -l < "$SCRIPT_DIR/../CONVENTIONS.md")"
+    delta=$((bp_lines - proj_lines))
+    if [ $delta -gt 20 ]; then
+      STALE_FILES+=("CONVENTIONS.md")
+      log_warn "CONVENTIONS.md: $delta lines behind bigpowers template — consider updating"
+    fi
+  fi
+}
+
+migrate_write_report() {
+  local m ISO_DATE FAILED_COUNT
+  ISO_DATE="$(date -u +%Y-%m-%dT%H%M%SZ)"
+  REPORT_FILE="$SPECS_DIR/migration-report-$ISO_DATE.md"
+
+  cat > "$REPORT_FILE" <<REPORT
+# Migration Report — $ISO_DATE
+
+## Gap Summary
+
+| Field | Value |
+|-------|-------|
+| Detected version | $DETECTED |
+| Installed version | $INSTALLED |
+| Migration count | ${MIGRATION_COUNT:-0} |
+
+## Migrations Applied
+
+REPORT
+
+  for m in "${SUCCEEDED[@]:-}"; do
+    [ -z "$m" ] && continue
+    echo "- $m PASS" >> "$REPORT_FILE"
+  done
+  FAILED_COUNT="${#FAILED[@]}"
+  if [ "${FAILED_COUNT}" -gt 0 ]; then
+    echo "" >> "$REPORT_FILE"
+    echo "## Migrations Failed" >> "$REPORT_FILE"
+    for m in "${FAILED[@]}"; do
+      echo "- $m FAIL" >> "$REPORT_FILE"
+    done
+  fi
+  if [ ${#SKIPPED[@]} -gt 0 ]; then
+    echo "" >> "$REPORT_FILE"
+    echo "## Skipped" >> "$REPORT_FILE"
+    for m in "${SKIPPED[@]}"; do
+      echo "- $m" >> "$REPORT_FILE"
+    done
+  fi
+  echo "" >> "$REPORT_FILE"
+  echo "## Uncertainties" >> "$REPORT_FILE"
+  echo "WARN count: $UNCERTAINTY_COUNT — review specs/ for GUESS markers and adjust if needed." >> "$REPORT_FILE"
+  echo "" >> "$REPORT_FILE"
+  echo "## Verification" >> "$REPORT_FILE"
+  echo "- validate-specs-yaml: ran as final gate" >> "$REPORT_FILE"
+
+  if [ ${#STALE_FILES[@]} -gt 0 ]; then
+    echo "" >> "$REPORT_FILE"
+    echo "## Staleness Notice" >> "$REPORT_FILE"
+    for f in "${STALE_FILES[@]:-}"; do
+      [ -z "$f" ] && continue
+      echo "- $f is behind the current bigpowers template" >> "$REPORT_FILE"
+    done
+  fi
+
+  echo "" >> "$REPORT_FILE"
+  echo "## Next Steps" >> "$REPORT_FILE"
+  echo "1. Review the migration report and verify spec correctness" >> "$REPORT_FILE"
+  echo "2. Run \`bash scripts/sync-skills.sh\` to regenerate agent artifacts" >> "$REPORT_FILE"
+  echo "3. Commit changes if not auto-committed" >> "$REPORT_FILE"
+  echo "" >> "$REPORT_FILE"
+  echo "## Rollback" >> "$REPORT_FILE"
+  echo "To rollback, restore from backup:" >> "$REPORT_FILE"
+  echo "\`\`\`bash" >> "$REPORT_FILE"
+  echo "rm -rf specs/ && cp -r $BACKUP_DIR/ specs/" >> "$REPORT_FILE"
+  echo "\`\`\`" >> "$REPORT_FILE"
+
+  log_done "Migration report: $REPORT_FILE"
+}
+
+migrate_print_summary() {
+  echo ""
+  echo "=========================================="
+  echo "  Migration complete: $DETECTED -> $INSTALLED"
+  echo "=========================================="
+  echo "  Applied:  ${#SUCCEEDED[@]}"
+  echo "  Failed:   ${#FAILED[@]}"
+  echo "  Skipped:  ${#SKIPPED[@]}"
+  echo "  WARN:     $UNCERTAINTY_COUNT"
+  [ ${#STALE_FILES[@]} -gt 0 ] && echo "  Stale:    ${STALE_FILES[*]:-}"
+  echo "  Report:   $REPORT_FILE"
+  echo "=========================================="
+  echo "  Remember: run 'bash scripts/sync-skills.sh'"
+  echo "=========================================="
+}
+
+migrate_auto_commit() {
+  local COMMIT_MSG
+  if [ "$SKIP_COMMIT" != "true" ] && [ "${MIGRATION_COUNT:-0}" -gt 0 ]; then
+    log_info "Auto-committing migration …"
+    git -C "$REPO_ROOT" add specs/ 2>/dev/null || true
+    COMMIT_MSG="migrate-version: $DETECTED -> $INSTALLED (${MIGRATION_COUNT:-0} migration(s))"
+    if git -C "$REPO_ROOT" commit -m "$COMMIT_MSG" 2>/dev/null; then
+      log_done "committed: $COMMIT_MSG"
+    else
+      log_info "nothing to commit (already clean)"
+    fi
+  fi
+}
+
+migrate_finalize() {
+  migrate_stamp_version
+  migrate_run_soft_gates
+  migrate_check_staleness
+  migrate_write_report
+  migrate_print_summary
+  migrate_auto_commit
+}

package/scripts/lib/migrate-version-run.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# story: e44s03 e44s04
+# migrate-version orchestrator — sources lib modules and runs the migration pipeline
+
+if [ -n "${MIGRATE_VERSION_RUN_LOADED:-}" ]; then return 0; fi
+MIGRATE_VERSION_RUN_LOADED=1
+
+_LIB="$(dirname "${BASH_SOURCE[0]}")"
+source "$_LIB/migrate-version-common.sh"
+source "$_LIB/migrate-version-plan.sh"
+source "$_LIB/migrate-version-transforms.sh"
+source "$_LIB/migrate-version-execute.sh"
+source "$_LIB/migrate-version-post.sh"
+
+migrate_version_main() {
+  if [ "$FORCE" != "true" ]; then
+    migrate_preflight_block || exit $?
+  fi
+
+  if [ ! -d "$SPECS_DIR" ]; then
+    echo "migrate-version: no specs/ directory found" >&2
+    exit 2
+  fi
+  if [ ! -f "$REGISTRY" ]; then
+    echo "migrate-version: migration registry not found at $REGISTRY" >&2
+    exit 4
+  fi
+
+  INSTALLED="$(migrate_installed_version)"
+  migrate_detect_version || exit $?
+
+  echo "migrate-version: detected=$DETECTED installed=$INSTALLED"
+
+  if [ "$DETECTED" = "$INSTALLED" ]; then
+    echo "migrate-version: no version gap — specs are current"
+    exit 0
+  fi
+
+  migrate_build_plan
+
+  if [ "$DRY_RUN" != "true" ]; then
+    migrate_backup_specs
+  fi
+
+  if [ "$DRY_RUN" = "true" ]; then
+    migrate_print_dry_run
+    exit 0
+  fi
+
+  migrate_execute_migrations
+  migrate_finalize
+  exit 0
+}