feat: add version constraint validation for atmos.yaml

Add ability to enforce Atmos version requirements in atmos.yaml configuration.
Teams can now ensure consistent Atmos versions across developers and CI/CD.

Configuration:
- version.constraint.require: semver constraint (e.g., ">=1.100.0, <2.0.0")
- version.constraint.enforcement: fatal|warn|silent (default: fatal)
- version.constraint.message: custom error message
- ATMOS_VERSION_ENFORCEMENT env var override

Uses hashicorp/go-version library (already in go.mod) for Terraform-compatible
constraint syntax including pessimistic operator (~>).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: osterman

CLAUDE.md

@@ -417,7 +417,7 @@ Follow template (what/why/references).
 **Blog Posts (CI Enforced):**
 - PRs labeled `minor`/`major` MUST include blog post: `website/blog/YYYY-MM-DD-feature-name.mdx`
 - Use `.mdx` with YAML front matter, `<!--truncate-->` after intro
-- Tags: User-facing (`feature`/`enhancement`/`bugfix`) or Contributors (`contributors`)
+- **ONLY use existing tags** - check `website/blog/*.mdx` for valid tags before writing
 - Author: committer's GitHub username, add to `website/blog/authors.yml`
 
 **Blog Template:**
@@ -433,11 +433,14 @@ Brief intro.
 ## What Changed / Why This Matters / How to Use It / Get Involved
 ```
 
-**Tag Reference:**
-- Primary: `feature`, `enhancement`, `bugfix`, `contributors`
-- Technical (contributor): `atmos-core`, `refactoring`, `testing`, `ci-cd`, `developer-experience`
-- Technical (user): `terraform`, `helmfile`, `workflows`, `validation`, `performance`, `cloud-architecture`
-- General: `announcements`, `breaking-changes`
+**Existing Tags (use only these):**
+- Primary: `feature`, `enhancement`, `bugfix`
+- Secondary: `dx`, `security`, `documentation`, `core`, `breaking-change`
+
+**Finding valid tags:**
+```bash
+grep -h "^  - " website/blog/*.mdx | sort | uniq -c | sort -rn
+```
 
 Use `no-release` label for docs-only changes.
 

docs/prd/version-constraint.md

@@ -276,7 +276,20 @@ ATMOS_VERSION_ENFORCEMENT=silent atmos terraform plan
 
 **File Changes:**
 
-1. **`pkg/schema/version.go`** - Add `VersionConstraint` struct
+1. **`errors/errors.go`** - Add sentinel errors for version constraint validation
+   ```go
+   // Version constraint errors.
+   var (
+       // ErrVersionConstraint indicates the current Atmos version does not satisfy
+       // the version constraint specified in atmos.yaml.
+       ErrVersionConstraint = errors.New("version constraint not satisfied")
+
+       // ErrInvalidVersionConstraint indicates the version constraint syntax is invalid.
+       ErrInvalidVersionConstraint = errors.New("invalid version constraint")
+   )
+   ```
+
+2. **`pkg/schema/version.go`** - Add `VersionConstraint` struct
    ```go
    type VersionConstraint struct {
        Require     string `yaml:"require,omitempty" mapstructure:"require" json:"require,omitempty"`
@@ -290,7 +303,7 @@ ATMOS_VERSION_ENFORCEMENT=silent atmos terraform plan
    }
    ```
 
-2. **`pkg/version/constraint.go`** (new file) - Validation logic
+3. **`pkg/version/constraint.go`** (new file) - Validation logic (returns errors, no deep exits)
    ```go
    package version
 
@@ -321,7 +334,7 @@ ATMOS_VERSION_ENFORCEMENT=silent atmos terraform plan
    }
    ```
 
-3. **`pkg/version/constraint_test.go`** (new file) - Comprehensive tests
+4. **`pkg/version/constraint_test.go`** (new file) - Comprehensive tests
    ```go
    package version
 
@@ -426,7 +439,7 @@ ATMOS_VERSION_ENFORCEMENT=silent atmos terraform plan
    }
    ```
 
-4. **`cmd/cmd_utils.go`** - Add validation call in `initConfig()`
+5. **`cmd/cmd_utils.go`** - Add validation call in `initConfig()`
    ```go
    // Add after config is loaded, before any command execution
    func initConfig() error {
@@ -440,6 +453,8 @@ ATMOS_VERSION_ENFORCEMENT=silent atmos terraform plan
        return nil
    }
 
+   // validateVersionConstraint uses the Atmos error builder pattern.
+   // No deep exits - all errors are returned for proper propagation.
    func validateVersionConstraint(cfg *schema.AtmosConfiguration) error {
        constraint := cfg.Version.Constraint
 
@@ -464,42 +479,60 @@ ATMOS_VERSION_ENFORCEMENT=silent atmos terraform plan
            return nil
        }
 
-       // Validate constraint
+       // Validate constraint syntax
        satisfied, err := version.ValidateConstraint(constraint.Require)
        if err != nil {
-           // Invalid constraint syntax is always fatal
-           return fmt.Errorf("invalid version constraint in configuration: %w", err)
+           // Invalid constraint syntax is always fatal - use error builder
+           return errUtils.Build(errUtils.ErrInvalidVersionConstraint).
+               WithHint("Please use valid semver constraint syntax").
+               WithHint("Reference: https://github.com/hashicorp/go-version").
+               WithContext("constraint", constraint.Require).
+               WithExitCode(1).
+               Wrap(err)
        }
 
        if !satisfied {
-           // Build error message
-           msg := constraint.Message
-           if msg == "" {
-               msg = fmt.Sprintf(
-                   "This configuration requires Atmos version %s.\nPlease upgrade: https://atmos.tools/install",
-                   constraint.Require,
-               )
+           // Build hints for error message
+           hints := []string{
+               fmt.Sprintf("This configuration requires Atmos version %s", constraint.Require),
+               "Please upgrade: https://atmos.tools/install",
            }
 
-           fullMsg := fmt.Sprintf(
-               "Atmos version constraint not satisfied\n  Required: %s\n  Current:  %s\n\n%s",
-               constraint.Require,
-               version.Version,
-               msg,
-           )
+           // Add custom message as hint if provided
+           if constraint.Message != "" {
+               hints = append(hints, constraint.Message)
+           }
 
            if enforcement == "fatal" {
-               return fmt.Errorf(fullMsg)
+               // Use error builder for proper error handling
+               builder := errUtils.Build(errUtils.ErrVersionConstraint).
+                   WithContext("required", constraint.Require).
+                   WithContext("current", version.Version).
+                   WithExitCode(1)
+
+               for _, hint := range hints {
+                   builder = builder.WithHint(hint)
+               }
+
+               return builder.Err()
            } else if enforcement == "warn" {
-               ui.Warning(fullMsg)
+               // Warnings still go to UI, but no error returned
+               ui.Warning(fmt.Sprintf(
+                   "Atmos version constraint not satisfied\n  Required: %s\n  Current:  %s",
+                   constraint.Require,
+                   version.Version,
+               ))
+               if constraint.Message != "" {
+                   ui.Warning(constraint.Message)
+               }
            }
        }
 
        return nil
    }
    ```
 
-5. **`pkg/datafetcher/schema/atmos/1.0.json`** - Update JSON schema
+6. **`pkg/datafetcher/schema/atmos/1.0.json`** - Update JSON schema
    ```json
    {
      "version": {
@@ -660,6 +693,46 @@ VERSION   PUBLISHED            TYPE      NOTES
   Use --constraint-aware to filter results
 ```
 
+## Error Handling
+
+### No Deep Exits
+
+This feature uses the **Atmos error builder pattern** for all error handling. There are **no deep exits** (`os.Exit()`, `log.Fatal()`, etc.) in the implementation.
+
+All errors are propagated up the call stack using Go's standard error return pattern, allowing:
+- Proper error wrapping with context
+- Consistent error formatting via the error builder
+- Exit codes set via `errUtils.WithExitCode()`
+- Testability without mocking `os.Exit()`
+
+```go
+// CORRECT: Use error builder pattern
+func validateVersionConstraint(cfg *schema.AtmosConfiguration) error {
+    // ... validation logic ...
+
+    if !satisfied {
+        return errUtils.Build(errUtils.ErrVersionConstraint).
+            WithHint(fmt.Sprintf("This configuration requires Atmos version %s", constraint.Require)).
+            WithHint("Please upgrade: https://atmos.tools/install").
+            WithContext("required", constraint.Require).
+            WithContext("current", version.Version).
+            WithExitCode(1).
+            Err()
+    }
+    return nil
+}
+
+// WRONG: Never use deep exits
+func validateVersionConstraint(cfg *schema.AtmosConfiguration) {
+    // ... validation logic ...
+
+    if !satisfied {
+        fmt.Fprintf(os.Stderr, "Version mismatch\n")
+        os.Exit(1)  // ❌ NEVER do this
+    }
+}
+```
+
 ## Error Messages
 
 **Fatal Error (enforcement: fatal):**

errors/errors.go

@@ -301,6 +301,10 @@ var (
 	ErrVersionCacheLoadFailed = errors.New("failed to load version check cache")
 	ErrVersionGitHubAPIFailed = errors.New("failed to query GitHub API for releases")
 
+	// Version constraint errors.
+	ErrVersionConstraint        = errors.New("version constraint not satisfied")
+	ErrInvalidVersionConstraint = errors.New("invalid version constraint")
+
 	// Atlantis errors.
 	ErrAtlantisInvalidFlags          = errors.New("incompatible atlantis flags")
 	ErrAtlantisProjectTemplateNotDef = errors.New("atlantis project template is not defined")

pkg/config/utils.go

@@ -8,11 +8,14 @@ import (
 	"strconv"
 	"strings"
 
+	errUtils "github.com/cloudposse/atmos/errors"
 	log "github.com/cloudposse/atmos/pkg/logger"
 	"github.com/cloudposse/atmos/pkg/perf"
 	"github.com/cloudposse/atmos/pkg/schema"
 	"github.com/cloudposse/atmos/pkg/store"
+	"github.com/cloudposse/atmos/pkg/ui"
 	u "github.com/cloudposse/atmos/pkg/utils"
+	"github.com/cloudposse/atmos/pkg/version"
 )
 
 // FindAllStackConfigsInPathsForStack finds all stack manifests in the paths specified by globs for the provided stack.
@@ -434,6 +437,87 @@ func checkConfig(atmosConfig schema.AtmosConfiguration, isProcessStack bool) err
 		}
 	}
 
+	// Validate version constraint.
+	if err := validateVersionConstraint(atmosConfig.Version.Constraint); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+// getVersionEnforcement returns the enforcement level, checking env var override.
+func getVersionEnforcement(configEnforcement string) string {
+	if envEnforcement := os.Getenv("ATMOS_VERSION_ENFORCEMENT"); envEnforcement != "" { //nolint:forbidigo
+		return envEnforcement
+	}
+	if configEnforcement == "" {
+		return "fatal"
+	}
+	return configEnforcement
+}
+
+// buildVersionConstraintError builds the error for unsatisfied version constraint.
+func buildVersionConstraintError(constraint schema.VersionConstraint) error {
+	builder := errUtils.Build(errUtils.ErrVersionConstraint).
+		WithExplanationf("This configuration requires Atmos version %s, but you are running %s",
+			constraint.Require, version.Version).
+		WithHint("Please upgrade: https://atmos.tools/install").
+		WithContext("required", constraint.Require).
+		WithContext("current", version.Version).
+		WithExitCode(1)
+
+	if constraint.Message != "" {
+		builder = builder.WithHint(constraint.Message)
+	}
+
+	return builder.Err()
+}
+
+// warnVersionConstraint logs a warning for unsatisfied version constraint.
+func warnVersionConstraint(constraint schema.VersionConstraint) {
+	_ = ui.Warning(fmt.Sprintf(
+		"Atmos version constraint not satisfied\n  Required: %s\n  Current:  %s",
+		constraint.Require,
+		version.Version,
+	))
+	if constraint.Message != "" {
+		_ = ui.Warning(constraint.Message)
+	}
+}
+
+// validateVersionConstraint validates the current Atmos version against the constraint
+// specified in atmos.yaml. Uses the Atmos error builder pattern - no deep exits.
+func validateVersionConstraint(constraint schema.VersionConstraint) error {
+	if constraint.Require == "" {
+		return nil
+	}
+
+	enforcement := getVersionEnforcement(constraint.Enforcement)
+	if enforcement == "silent" {
+		return nil
+	}
+
+	satisfied, err := version.ValidateConstraint(constraint.Require)
+	if err != nil {
+		return errUtils.Build(errors.Join(errUtils.ErrInvalidVersionConstraint, err)).
+			WithHint("Please use valid semver constraint syntax").
+			WithHint("Reference: https://github.com/hashicorp/go-version").
+			WithContext("constraint", constraint.Require).
+			WithExitCode(1).
+			Err()
+	}
+
+	if satisfied {
+		return nil
+	}
+
+	switch enforcement {
+	case "fatal":
+		return buildVersionConstraintError(constraint)
+	case "warn":
+		warnVersionConstraint(constraint)
+	}
+
 	return nil
 }