v1.223.1-rc.3

test: cover Terraform same-stack dependency order Erik Osterman (Cloud Posse) (@osterman) (#2776)

## what

• Add a credential-free eight-component Terraform dependency fixture that mirrors the reported same-stack graph.
• Exercise canonical component:, name: alias, and legacy settings.depends_on declarations through terraform plan --all --dry-run -s <stack>.
• Assert the execution summary contains only the selected stack and every prerequisite completes before its dependent starts.

why

• Prevent the scheduler from again diverging from dependency-list rendering for the dependencies.components[].name form addressed by #2755.
• Preserve compatibility coverage for canonical and legacy dependency declarations without Terraform, credentials, or state backends.

references

• #2755

🚀 Enhancements

fix(config): resolve atmos.yaml imports relative to config dir Brian Ojeda (@sgtoj) (#2772)

## what

• Top-level import: entries in atmos.yaml now resolve relative to the directory containing that atmos.yaml, not the current working directory. Running a command from a subdirectory no longer breaks imports like import: [".atmos/commands/**/*"].
• Anchoring is scoped to config-sourced empty and dot-relative base paths ("", ., ./, .., ../…). Bare paths (foo), absolute paths, !cwd, and runtime overrides (ATMOS_BASE_PATH, --base-path, the atmos_base_path provider parameter) keep their existing resolution semantics.
• Base-path provenance is tracked across multiple --config files and through imported declarations, so a later --config file's imports anchor to the file that actually declared the effective base_path.
• Nested imports (local and go-getter adapters) resolve a declared relative base_path against the importing file's directory via a shared helper.

why

• mergeImports resolved the import base path with filepath.Abs(base_path), which anchors to the current working directory. With the common empty or dot-relative base_path (e.g. .), running atmos from a nested directory resolved import: globs against the subdirectory and failed to find them — for example, atmos.yaml at /repo/acme with import: [".atmos/commands/**/*"], invoked from /repo/acme/somepath, looked for .atmos/commands under somepath.
• Imports should anchor to the atmos root (the directory of the discovered atmos.yaml), consistent with how base_path is resolved for config-file sources.
• The change preserves the established source-aware convention (runtime/CLI/env dot paths → CWD; bare paths → git-root search; !cwd → CWD), so anchoring is limited to config-sourced empty and dot-relative values.

references

• Fix record: docs/fixes/2026-07-20-config-imports-relative-to-config-dir.md.
• Related base-path work: docs/prd/base-path-resolution-semantics.md, docs/fixes/2026-03-17-failed-to-find-import-base-path-resolution.md.
• Testing: go build ./...; go test ./pkg/config/... ./internal/exec/... ./cmd/...; the new CWD-independence tests fail on the pre-fix code (import resolves against CWD) and pass after; go test ./pkg/config ./pkg/config/adapters -shuffle=on -count=10 for registry isolation.

Summary by CodeRabbit

• Bug Fixes
  • Resolved import: globs and relative import paths relative to the declaring config file’s directory (not the process working directory).
  • Fixed how imported base_path is anchored and prioritized across nested imports and multi-file merges, including correct handling of CWD-anchored (!cwd) behavior and bare/empty base paths.
  • Improved resilience when nested import base paths can’t be resolved or provenance read fails—continuing without breaking the whole resolve.
• Documentation
  • Documented the updated config-relative import behavior and compatibility rules.
• Tests
  • Expanded validation for base-path resolution, glob/relative imports, merge precedence, and new error-path scenarios.

fix(version): clarify Git ref version override guidance Erik Osterman (Cloud Posse) (@osterman) (#2775)

## what

• Add ref:<name> and ref:main guidance to invalid --use-version errors.
• Cover the bare main failure path and update the related blog and implementation documentation.

why

• Branch and tag override support already exists, but the stale hint and format lists made it appear unsupported.

references

• N/A

Summary by CodeRabbit

• New Features
  • Added ref:<name> to --use-version for selecting a Git branch or tag, resolved to the latest available build artifact.
• Documentation
  • Updated version-format guidance and “Invalid version format” messaging to include ref:<name> (along with pr:NNNN, sha:XXXXXXX, and semver).
  • Refreshed the PRD sections covering security mitigations and testing strategy to reflect the new ref approach.
• Bug Fixes
  • Improved the invalid version-spec error hint to explicitly show the supported ref:<name> format.
• Tests
  • Adjusted unit tests to validate the revised error messaging for invalid version input.

fix(terraform): preserve sensitive output types when masking is disabled Erik Osterman (Cloud Posse) (@osterman) (#2770)

## what

• Make --mask=false opt out of sensitive Terraform/OpenTofu output registration, retaining structured values in generated JSON varfiles.
• Add coverage for the default secret-safe TF_VAR_* path and the disabled-masking compatibility path.
• Document the resulting disk-exposure tradeoff.

why

• Environment variables are strings, so untyped structured values cannot retain their object shape when sensitive-output registration routes them through TF_VAR_*.

references

Closes #2768

Summary by CodeRabbit

• Bug Fixes
  • When secret masking is disabled, sensitive Terraform/OpenTofu outputs keep their original structured (object/typed) form.
  • Masking/secret-safe handling is applied only when masking is enabled; with masking off, secret-safe TF_VAR_ handling may not apply and values can appear in generated .tfvars.json.
• Documentation
  • Added clearer warnings about the behavior and security implications of disabling masking, and improved formatting of a logging-related example.
• Tests
  • Added regression coverage for masking-disabled behavior to prevent unintended transformations.

fix(cast): record help output once Erik Osterman (Cloud Posse) (@osterman) (#2774)

## what

• Record help casts through the masked I/O stream once, and cover the lifecycle and rendered help output with regression tests.
• Regenerate CLI screengrabs, validate one USAGE heading per help cast, and add missing MCP help assets.

why

• The help-specific recorder tee duplicated every rendered help block in docs casts.
• Complete, validated screengrabs prevent both duplicate payloads and broken documented embeds.

references

• None.