feat(boatstack): non-breaking versioned configuration schema migration system

labs/12-product-engineering-loop/boatstack-distribution/release-notes/2026-07-20-config-schema-migration.md

@@ -0,0 +1,3 @@
+### Versioned configuration schema migration system
+
+Introduced a non-breaking, versioned configuration migration system for `.boatstack-project.json`. Older configurations are automatically upgraded to the latest schema version during `/boatstack-update`, with full dry-run reporting, schema gap detection, and helpful error messages for newer configuration versions. A generated configuration schema reference document (`CONFIG_SCHEMA.md`) is now embedded and distributed in the product bundle.

labs/12-product-engineering-loop/product-engineering-loop/cmd/boatstack-helper/main.go

@@ -1,10 +1,12 @@
 package main
 
 import (
+	"encoding/json"
 	"flag"
 	"fmt"
 	"io"
 	"os"
+	"path/filepath"
 	"sort"
 	"strings"
 	"time"
@@ -513,6 +515,67 @@ func checkSafetyCommand(arguments []string) int {
 	return 0
 }
 
+type MigrateConfigReport struct {
+	Status      string `json:"status"`
+	Message     string `json:"message,omitempty"`
+	FromVersion int    `json:"from_version"`
+	ToVersion   int    `json:"to_version"`
+	Changed     bool   `json:"changed"`
+}
+
+func migrateConfigCommand(arguments []string) int {
+	flags := flag.NewFlagSet("migrate-config", flag.ContinueOnError)
+	repo := flags.String("repo", ".", "repository whose configuration should be migrated")
+	check := flags.Bool("check", false, "dry-run check mode")
+	if err := flags.Parse(arguments); err != nil {
+		return 2
+	}
+	configPath := filepath.Join(*repo, ".boatstack-project.json")
+	raw, err := os.ReadFile(configPath)
+	if err != nil {
+		report := MigrateConfigReport{
+			Status:  "FAIL",
+			Message: fmt.Sprintf("failed to read config: %v", err),
+		}
+		value, _ := json.Marshal(report)
+		fmt.Print(string(value))
+		return 1
+	}
+	upgraded, fromVer, toVer, changed, err := boatstack.MigrateConfigBytes(raw)
+	if err != nil {
+		report := MigrateConfigReport{
+			Status:  "FAIL",
+			Message: fmt.Sprintf("migration failed: %v", err),
+		}
+		value, _ := json.Marshal(report)
+		fmt.Print(string(value))
+		return 1
+	}
+	if changed && !*check {
+		if err := os.WriteFile(configPath, upgraded, 0o644); err != nil {
+			report := MigrateConfigReport{
+				Status:  "FAIL",
+				Message: fmt.Sprintf("failed to write migrated config: %v", err),
+			}
+			value, _ := json.Marshal(report)
+			fmt.Print(string(value))
+			return 1
+		}
+	}
+	report := MigrateConfigReport{
+		Status:      "PASS",
+		FromVersion: fromVer,
+		ToVersion:   toVer,
+		Changed:     changed,
+	}
+	value, err := json.Marshal(report)
+	if err != nil {
+		return fail(err)
+	}
+	fmt.Print(string(value))
+	return 0
+}
+
 func prContextCommand(arguments []string) int {
 	flags := flag.NewFlagSet("pr-context", flag.ContinueOnError)
 	repo := flags.String("repo", ".", "repository whose branch should be projected")
@@ -665,7 +728,7 @@ func workspaceStatusCommand(arguments []string) int {
 
 func run() int {
 	if len(os.Args) < 2 {
-		fmt.Fprintln(os.Stderr, "usage: boatstack-helper <init|update|check-update|release-classify|next-patch|export|check-source-plan|planning-write|check-plan|record-approval|activate-plan|delivery-status|next-status|run-preflight|record-change|record-delivery-gate|check-safety|safety-hook|diagnose-hook|pr-context|check-pr|publish-pr|workspace-cut|workspace-cleanup|workspace-status|doctor|version>")
+		fmt.Fprintln(os.Stderr, "usage: boatstack-helper <init|update|check-update|release-classify|next-patch|export|check-source-plan|planning-write|check-plan|record-approval|activate-plan|delivery-status|next-status|run-preflight|record-change|record-delivery-gate|check-safety|migrate-config|safety-hook|diagnose-hook|pr-context|check-pr|publish-pr|workspace-cut|workspace-cleanup|workspace-status|doctor|version>")
 		return 2
 	}
 	switch os.Args[1] {
@@ -723,6 +786,8 @@ func run() int {
 		return workspaceCleanupCommand(os.Args[2:])
 	case "workspace-status":
 		return workspaceStatusCommand(os.Args[2:])
+	case "migrate-config":
+		return migrateConfigCommand(os.Args[2:])
 	case "version":
 		fmt.Printf("Boatstack %s (%s)\n", boatstack.Version, boatstack.SourceCommit)
 		return 0

labs/12-product-engineering-loop/product-engineering-loop/export.go

@@ -96,8 +96,14 @@ func LoadConfig(path string) (ProjectConfig, []byte, error) {
 }
 
 func ValidateConfig(config ProjectConfig) error {
-	if config.SchemaVersion != 1 {
-		return fmt.Errorf("project config schema_version must be 1")
+	if config.SchemaVersion < 1 {
+		return fmt.Errorf("project config schema_version must be >= 1")
+	}
+	if config.SchemaVersion > currentSchemaVersion() {
+		return fmt.Errorf("config was written by a newer Boatstack; update Boatstack")
+	}
+	if config.SchemaVersion < currentSchemaVersion() {
+		return fmt.Errorf("config schema is behind; run /boatstack-update")
 	}
 	if strings.TrimSpace(config.Project.Name) == "" {
 		return fmt.Errorf("project.name is required")
@@ -217,7 +223,7 @@ func BuildExportBundle(configPath string, config ProjectConfig, rawConfig []byte
 		}
 	}
 
-	for _, name := range []string{"workflow.md", "artifacts.md", "failure-moves.md", "irreversible-operation-boundary.md", "host-hook-contracts.md"} {
+	for _, name := range []string{"workflow.md", "artifacts.md", "failure-moves.md", "irreversible-operation-boundary.md", "host-hook-contracts.md", "config-schema.md"} {
 		value, err := readCanonical("references/" + name)
 		if err != nil {
 			return ExportBundle{}, err

labs/12-product-engineering-loop/product-engineering-loop/init.go

@@ -313,9 +313,26 @@ func RunInit(options InitOptions) (returnErr error) {
 	}
 	var config ProjectConfig
 	var rawConfig []byte
+	var migrationFrom, migrationTo int
+	var migrationChanged bool
 	if configExists {
-		config, rawConfig, err = LoadConfig(configPath)
+		var err error
+		rawConfig, err = os.ReadFile(configPath)
 		if err != nil {
+			return err
+		}
+		var upgraded []byte
+		upgraded, migrationFrom, migrationTo, migrationChanged, err = MigrateConfigBytes(rawConfig)
+		if err != nil {
+			return fmt.Errorf("failed to migrate project config: %w", err)
+		}
+		if migrationChanged {
+			rawConfig = upgraded
+		}
+		if err := DecodeJSON("load project configuration", configPath, rawConfig, &config); err != nil {
+			return fmt.Errorf("existing Boatstack config is invalid: %w", err)
+		}
+		if err := ValidateConfig(config); err != nil {
 			return fmt.Errorf("existing Boatstack config is invalid: %w", err)
 		}
 	} else {
@@ -508,7 +525,11 @@ func RunInit(options InitOptions) (returnErr error) {
 			return scopeErr
 		}
 		fmt.Fprintf(options.Output, "\nPASS: Boatstack updated to %s on a dedicated infrastructure branch.\n", Version)
-		fmt.Fprintln(options.Output, "PASS: no product files changed.")
+		if migrationChanged {
+			fmt.Fprintf(options.Output, "PASS: migrated .boatstack-project.json from schema version %d to %d.\n", migrationFrom, migrationTo)
+		} else {
+			fmt.Fprintln(options.Output, "PASS: no product files changed.")
+		}
 		fmt.Fprintln(options.Output, "Changed Boatstack paths:")
 		for _, path := range changed {
 			fmt.Fprintln(options.Output, "  "+path)

labs/12-product-engineering-loop/product-engineering-loop/migrate.go

@@ -0,0 +1,101 @@
+package boatstack
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+)
+
+const CurrentConfigSchemaVersion = 1
+
+var currentConfigSchemaVersionOverride = CurrentConfigSchemaVersion
+
+type configMigration struct {
+	from  int
+	to    int
+	apply func(map[string]any) (map[string]any, error)
+}
+
+var configMigrations []configMigration
+
+func currentSchemaVersion() int {
+	return currentConfigSchemaVersionOverride
+}
+
+// MigrateConfigBytes migrates raw JSON configuration bytes to the latest CurrentConfigSchemaVersion.
+// It returns the upgraded JSON bytes, the original schema version, the final schema version,
+// a boolean indicating whether the content actually changed, and any error encountered.
+func MigrateConfigBytes(raw []byte) (upgraded []byte, from, to int, changed bool, err error) {
+	if len(strings.TrimSpace(string(raw))) == 0 {
+		return raw, 0, 0, false, nil
+	}
+
+	var partial map[string]any
+	if err := json.Unmarshal(raw, &partial); err != nil {
+		return nil, 0, 0, false, fmt.Errorf("failed to parse config JSON: %w", err)
+	}
+
+	targetVer := currentSchemaVersion()
+
+	var fromVer int
+	if v, exists := partial["schema_version"]; exists {
+		switch val := v.(type) {
+		case float64:
+			fromVer = int(val)
+		case int:
+			fromVer = val
+		default:
+			return nil, 0, 0, false, fmt.Errorf("schema_version must be an integer")
+		}
+	} else {
+		// Default to 1 if schema_version is missing
+		fromVer = 1
+	}
+
+	if fromVer > targetVer {
+		return nil, fromVer, 0, false, fmt.Errorf("config was written by a newer Boatstack; update Boatstack")
+	}
+
+	if fromVer == targetVer {
+		return raw, fromVer, fromVer, false, nil
+	}
+
+	currentVer := fromVer
+	data := partial
+
+	for currentVer < targetVer {
+		var found *configMigration
+		for i := range configMigrations {
+			if configMigrations[i].from == currentVer {
+				found = &configMigrations[i]
+				break
+			}
+		}
+
+		if found == nil {
+			return nil, fromVer, 0, false, fmt.Errorf("no migration found from version %d to %d", currentVer, currentVer+1)
+		}
+
+		var err error
+		data, err = found.apply(data)
+		if err != nil {
+			return nil, fromVer, 0, false, fmt.Errorf("failed to apply migration from %d to %d: %w", found.from, found.to, err)
+		}
+
+		if found.to <= currentVer {
+			return nil, fromVer, 0, false, fmt.Errorf("invalid migration path from %d to %d", found.from, found.to)
+		}
+
+		currentVer = found.to
+	}
+
+	data["schema_version"] = targetVer
+
+	upgraded, err = json.MarshalIndent(data, "", "  ")
+	if err != nil {
+		return nil, fromVer, 0, false, fmt.Errorf("failed to marshal migrated config: %w", err)
+	}
+	upgraded = append(upgraded, '\n')
+
+	return upgraded, fromVer, targetVer, true, nil
+}