Merge branch 'main' into renovate/floci-floci

Author: mergify[bot]

.claude/skills/atmos-terraform-state-migrations

@@ -0,0 +1 @@
+../../agent-skills/skills/atmos-terraform-state-migrations

.claude/skills/field-test/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: field-test
+description: "Hands-on manual DX test pass of a feature or CLI command: read the real implementation and tests, hypothesize plausible user misunderstandings and misuse automated tests don't cover, build durable fixtures, execute for real against real state, and report ranked findings. Investigation only — never fixes anything found. Invoke on explicit requests like 'field test X' / 'do a DX test pass on X' / 'find vibe-coded slop in X'."
+argument-hint: "Feature or command to test, e.g. 'atmos vendor pull'"
+metadata:
+  copyright: Copyright Cloud Posse, LLC 2026
+  version: "1.0.0"
+---
+
+# Field Test
+
+Hands-on, adversarial test pass of **`$ARGUMENTS`** (the feature/command named when this skill
+was invoked, e.g. `atmos vendor pull`). If no target was given, ask which feature/command to test
+before starting.
+
+Goal: catch "vibe-coded slop" — behavior that looks fine in code review but breaks or misleads a
+real user — not to re-run what automated tests already cover. Anticipate plausible user
+misunderstandings, not just obvious bugs.
+
+**This pass is investigation only.** Do not fix anything you find — see Phase 5. Report and stop;
+the user decides what to fix (and when they do, that follow-up work should close with the
+`fix-log` skill, not this one).
+
+## Phase 1 — Research before touching anything
+
+The goal is a map of "documented or plausible usage" minus "already tested" = what needs manual
+verification. This phase is broad, read-only research — delegate it to `Agent subagent_type:
+"Explore"` (1-3 agents in parallel, one per bullet below) rather than doing it all serially inline.
+
+- **Implementation** — the actual code, not just its docs or the skill describing it. Per this
+  repo's conventions, business logic lives in narrow `pkg/` packages, not `internal/exec/` (being
+  phased out) — check both `cmd/<command>/` (thin call site) and the `pkg/` package(s) it
+  delegates to for the real logic and error paths.
+- **Docs and skills** — every relevant page under `website/docs/cli/commands/`, the matching
+  `.claude/skills/atmos-*` skill(s) for the subsystem, and any README describing the feature. Note
+  anything phrased with confidence you haven't independently confirmed against the code — docs and
+  skills describe intended behavior, not necessarily current behavior.
+- **Existing automated tests** — unit tests colocated with the code, `tests/test-cases/` fixtures,
+  `tests/testdata/` golden snapshots. For each, note exactly what it does and doesn't exercise
+  (mocked vs. real execution, which flags/paths/backends are hit).
+- **Every flag, config option, and documented action/mode** — grep for them and list them. You
+  will need to touch every one in Phase 4.
+
+## Phase 2 — Generate hypotheses, don't just wander
+
+Before running anything, write down concrete things to try, prioritized by what a real user would
+plausibly do:
+
+- Every flag combination that seems natural but might not be validated (two flags that should be
+  mutually exclusive; two config fields whose combination is never cross-checked).
+- Every place the docs/skill claim something you haven't verified against actual code.
+- Any "safe-looking" command (`plan`/`preview`/`--dry-run`/`list`/`describe`) that might secretly
+  mutate state or trigger side effects, if built the same way as a mutating command — Atmos has
+  many of these pairs (e.g. `terraform plan` vs `apply`, `vendor diff` vs `pull`), so this is a
+  high-yield category here specifically.
+- Any action/mode described in docs but not exercised by ANY test or example in the repo — those
+  are the highest-yield targets; if nothing has ever run it for real, assume it's broken until you
+  prove otherwise.
+- Copy-paste/misconfiguration scenarios — what happens if a user copies a working stack/component
+  block and changes one field but forgets a related one?
+- Error messages — accurate, do they name the actual flags/values involved, do they suggest a fix
+  (per this repo's error-builder/hint conventions)?
+- Idempotency/rerun-safety — run the same operation twice; does the second run behave correctly?
+- Determinism — run the same read-only command several times with no state change between runs —
+  is the output identical every time?
+
+## Phase 3 — Build real, durable fixtures
+
+- Prefer extending or copying an existing fixture (`tests/test-cases/`, `examples/`, `demo/`) over
+  inventing one from scratch.
+- Build fixtures that exercise every documented capability, especially ones nothing in the repo
+  currently exercises. Make them realistic, not minimal-to-the-point-of-artificial.
+- If real infrastructure/emulators are available for what you're testing, use them for at least one
+  pass — this repo ships local AWS/GCP/Azure/Kubernetes/Vault/registry emulators for exactly this
+  purpose (see the `atmos-emulator` skill). Don't rely solely on mocked/dry-run paths, since that's
+  exactly what's already covered by automated tests.
+- Never manually edit golden snapshot files under `tests/test-cases/`, `tests/testdata/`, or
+  `tests/snapshots/` — regenerate them via `-regenerate-snapshots` per CLAUDE.md's Golden Snapshots
+  section.
+- Keep fixtures that have lasting value (they close real coverage gaps); don't create
+  scratch-and-delete throwaways unless truly one-off.
+
+## Phase 4 — Execute for real, with discipline
+
+- Run actual commands against a disposable fixture or emulator by default. Before any command that
+  can mutate state, obtain explicit user confirmation. Run against shared or production state only
+  with a documented backup and rollback plan. Don't reason abstractly about what "should" happen —
+  observe what does happen. Build a fresh binary first (`atmos build`) if the change under test
+  isn't already reflected in `./build/atmos`.
+- Never pipe redirection into a command under test — per CLAUDE.md, piping breaks TTY detection,
+  which can mask exactly the DX issues (interactive prompts, color, spinners) you're testing for.
+- **Before every test, verify you're actually starting from a clean/expected state — don't
+  assume.** Stale state from a previous run (yours or a prior session's) will silently corrupt your
+  results. Reset explicitly and confirm the reset worked (check a resource count/id changed, not
+  just that a command exited 0).
+- When something surprises you, reduce it to the smallest reproducible case and verify the repro
+  twice.
+- If Phase 1 research made a claim, verify it live before trusting it — code-reading can miss
+  control flow (e.g. assuming a flag is silently ignored when it actually errors, or vice versa).
+  Correct the record explicitly when research turns out wrong.
+- Test the happy path too, not just edge cases — confirm what's supposed to work actually does, so
+  the report distinguishes real regressions from things that were never broken.
+
+## Phase 5 — Report
+
+For every finding: exact repro command(s), expected vs. actual output, and severity (silent data
+loss/mutation > crash on reasonable input > confusing error message > cosmetic). Rank the report by
+severity, most dangerous first. Explicitly call out anything verified as working correctly too — a
+report that's only bad news is as misleading as one that's only good news.
+
+Keep a running scratch log of findings as you go (in your own working notes/task list) rather than
+reconstructing everything at the end from memory — but don't commit that log. Per CLAUDE.md's Git
+section, scratch/research files never get committed; only the fixtures built in Phase 3 (if kept
+for lasting value) and this final report are durable output.
+
+Do not fix anything found — this pass is investigation only. Stop and report; the user decides what
+to fix. End by invoking the `say` skill — a completed test pass reaching a stopping point a human
+should review is exactly its trigger.
+
+## Related
+
+- **`Explore` agent** — Phase 1's broad read-only research.
+- **`atmos-emulator` skill** — real local infra for Phase 3/4 when the target touches
+  AWS/GCP/Azure/Kubernetes.
+- **`docs` skill** — conventions for the CLI docs being cross-checked in Phase 1.
+- **`fix-log` skill** — for the user's follow-up once they decide what to fix; out of scope here.
+- **`say` skill** — end-of-pass notification.

.github/workflows/test.yml

@@ -547,7 +547,7 @@ jobs:
           FLOCI_GCP_ENDPOINT: "http://localhost:4588"
           FLOCI_AZURE_ENDPOINT: "http://localhost:4577"
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: go test ./tests -run 'Test((AWS(StoreHooks|Secrets)|GCPSecrets|AzureSecrets)FlociE2E|LocalGitOpsPushE2E|Scaffold(AWSLandingZone|GCPLandingZone|AzureLandingZone|AWSApp)FlociE2E|InitFromTemplateRepoGiteaE2E)' -count=1 -timeout 25m -v
+        run: go test ./tests -run 'Test((AWS(StoreHooks|Secrets)|GCPSecrets|AzureSecrets)FlociE2E|LocalGitOpsPushE2E|Scaffold(AWSLandingZone|GCPLandingZone|AzureLandingZone|AWSApp)FlociE2E|InitFromTemplateRepoGiteaE2E|TerraformFlociTfmigrateS3History)' -count=1 -timeout 25m -v
 
   # run k3s demo tests
   k3s:

agent-skills/AGENTS.md

@@ -104,6 +104,7 @@ When a task involves Atmos, activate the matching skill for detailed guidance.
 | Emulator components: AWS/GCP/Azure/Kubernetes/Vault/OpenBao/registry local emulators                                  | `atmos-emulator`        | `agent-skills/skills/atmos-emulator/SKILL.md`        |
 | Compositions: named service groupings and `atmos composition validate`                                                | `atmos-compositions`    | `agent-skills/skills/atmos-compositions/SKILL.md`    |
 | terraform plan/apply/deploy/destroy, workspace management, backend config, varfile generation                         | `atmos-terraform`       | `agent-skills/skills/atmos-terraform/SKILL.md`       |
+| Terraform state migrations with tfmigrate, migration HCL, migrate CLI, hooks, history mode, rerun safety              | `atmos-terraform-state-migrations` | `agent-skills/skills/atmos-terraform-state-migrations/SKILL.md` |
 | Terraform/OpenTofu linting: `atmos terraform lint`, TFLint configuration and rules, component toolchain pins, lifecycle hooks, SARIF CI findings | `atmos-lint` | `agent-skills/skills/atmos-lint/SKILL.md` |
 | helmfile sync/apply/destroy/diff, Kubernetes deployments, EKS integration, varfile generation                         | `atmos-helmfile`        | `agent-skills/skills/atmos-helmfile/SKILL.md`        |
 | Native Helm (experimental): Helm Go SDK template/diff/apply/delete, chart sources, values, repositories, provision targets | `atmos-helm`            | `agent-skills/skills/atmos-helm/SKILL.md`            |

agent-skills/skills/atmos-terraform-state-migrations/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: atmos-terraform-state-migrations
+description: "Terraform state migration workflow with tfmigrate in Atmos: writing migration HCL, running atmos terraform migrate plan/apply/list, wiring kind: tfmigrate hooks, configuring history mode, and handling state refactors, rerun safety, workspace context, backend history variables, and CI-safe migrations."
+metadata:
+  copyright: Copyright Cloud Posse, LLC 2026
+  version: "1.0.0"
+references:
+  - references/tfmigrate-migration-patterns.md
+---
+
+# Atmos Terraform State Migrations
+
+Use this skill when creating or reviewing Terraform state migrations for Atmos components. Atmos delegates state
+migrations to `tfmigrate`. It runs `tfmigrate` in the same component context as `atmos terraform plan` and `apply`.
+Before `tfmigrate` runs, Atmos performs auth identity setup, source and workdir provisioning, backend and varfile
+generation, Terraform init, workspace selection, toolchain resolution, and `TFMIGRATE_EXEC_PATH` setup.
+
+For migration HCL syntax and examples, load
+[references/tfmigrate-migration-patterns.md](references/tfmigrate-migration-patterns.md).
+
+## Start With Resolved Context
+
+Never guess stack names, component names, workspaces, backend paths, or state addresses.
+
+```bash
+atmos describe component <component> -s <stack>
+atmos terraform migrate list <component> -s <stack>
+atmos terraform state list <component> -s <stack>
+```
+
+Use the resolved component output to confirm:
+
+- the final Terraform component and component path
+- Terraform workspace name
+- backend type and backend settings
+- whether a `kind: tfmigrate` hook already exists
+- history key and history bucket from `atmos terraform migrate list`
+
+Use `atmos terraform state show <component> -s <stack> <address>` when resource identity or import IDs are unclear.
+If a refactor can be handled with Terraform `moved` blocks and stays in the same state, prefer that unless the user
+specifically needs `tfmigrate` automation or multi-state moves.
+
+## One-Off CLI Workflow
+
+Create a migration file in a project-owned migrations directory, then preview it before applying. `tfmigrate`
+resolves `--migration` relative to the `migration_dir` in its config. The Atmos-generated default config points
+`migration_dir` at the component's `migrations/` directory when one exists. Pass just the filename, not a
+`migrations/`-prefixed path.
+
+```bash
+atmos terraform migrate plan <component> -s <stack> --migration 20260527090000_refactor_vpc.hcl
+atmos terraform migrate apply <component> -s <stack> --migration 20260527090000_refactor_vpc.hcl
+```
+
+For multiple selected component instances:
+
+```bash
+atmos terraform migrate plan --components vpc,eks -s <stack> --migration 20260527090000_refactor.hcl
+atmos terraform migrate plan --query '.settings.requires_migration == true' --tfmigrate-config .tfmigrate.hcl
+atmos terraform migrate plan --affected --migration 20260527090000_refactor.hcl
+```
+
+Do not run `apply` until `plan` succeeds and the Terraform plan after migration does not show unintended destroy/create
+changes. `--affected` does not support `--include-dependents` for migrate.
+
+## Migration Files
+
+Use `tfmigrate` HCL for state operations that need reviewable, repeatable files. A migration file contains exactly one
+`migration` block.
+
+```hcl
+migration "state" "rename_subnet" {
+  actions = [
+    "mv aws_subnet.private aws_subnet.private_primary",
+  ]
+}
+```
+
+Common actions:
+
+- `mv <source> <destination>` for renames and module/address moves in one state.
+- `rm <addresses>...` for removing state bindings without destroying infrastructure.
+- `import <address> <id>` for binding existing infrastructure.
+- `replace-provider <from> <to>` for provider address migrations.
+- `xmv <source-pattern> <destination-pattern>` for wildcard moves.
+- `migration "multi_state"` for moving resources between component directories or state files.
+
+Keep migration filenames sortable, usually with a timestamp prefix. In history mode, unapplied migrations are processed
+in filename order.
+
+## Hook Wiring
+
+Use hooks when the migration should run as part of normal `plan`, `apply`, or `deploy` workflows.
+
+```yaml
+components:
+  terraform:
+    s3-bucket:
+      dependencies:
+        tools:
+          tfmigrate: "0.4.x"
+
+      hooks:
+        state-migration:
+          events:
+            - before.terraform.plan
+            - before.terraform.apply
+          kind: tfmigrate
+          migration: 20260527090000_remove_template_provider.hcl
+          mode: dynamic
+```
+
+`mode: dynamic` is the default. `before.terraform.plan` runs `tfmigrate plan`. `before.terraform.apply` and
+`before.terraform.deploy` run `tfmigrate apply`. Use `mode: plan` or `mode: apply` only when the hook must always run
+one action.
+
+Hook fields:
+
+- `migration`: path to one migration file.
+- `config`: path to `.tfmigrate.hcl`; omit `migration` when using history mode.
+- `backend_config`: entries passed as repeated `tfmigrate --backend-config` flags for the Terraform state backend.
+- `mode`: `dynamic`, `plan`, or `apply`.
+
+## History Mode
+
+Single-file `tfmigrate apply path.hcl` is not idempotent. A rerun can fail if a source address already moved, or an
+address was already removed. For CI-safe reruns, use `tfmigrate` history mode with durable storage.
+
+```yaml
+hooks:
+  state-migration:
+    events:
+      - before.terraform.plan
+      - before.terraform.apply
+    kind: tfmigrate
+    config: .tfmigrate.hcl
+    mode: dynamic
+```
+
+Atmos exposes helper variables for `.tfmigrate.hcl`:
+
+```hcl
+tfmigrate {
+  migration_dir = "./tfmigrate"
+
+  history {
+    storage "s3" {
+      bucket   = env.ATMOS_TFMIGRATE_HISTORY_BUCKET
+      key      = env.ATMOS_TFMIGRATE_HISTORY_KEY
+      region   = env.ATMOS_TFMIGRATE_HISTORY_REGION
+      role_arn = env.ATMOS_TFMIGRATE_HISTORY_ROLE_ARN
+    }
+  }
+}
+```
+
+The default history key is `tfmigrate/<stack>/<component>/<workspace>/history.json`. Atmos passes history settings to
+`tfmigrate`, but does not persist or repair history itself. Configure durable S3, GCS, or CI-persisted local storage.
+
+## Safety Checklist
+
+Before committing migration work:
+
+1. Confirm the migration addresses come from `atmos terraform state list`, not from code names alone.
+2. Confirm the migration file targets the resolved component working directory and workspace.
+3. Run `atmos terraform migrate plan` and inspect the post-migration Terraform plan.
+4. Use history mode for hooks or CI workflows that may rerun.
+5. Keep migration files and hook wiring in the same PR as the Terraform refactor they support.
+6. Remove or disable one-shot hook wiring after the migration has safely run everywhere it is intended to run.