docs(fixes): fix EditorConfig indentation in tfmigrate-hooks fix record

Ordered-list continuation lines used 3-space indentation, which fails this
repo's EditorConfig rule requiring multiples of 2 for markdown.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: osterman

docs/fixes/2026-08-03-registry-cache-parallel-platform-fetch.md

@@ -0,0 +1,75 @@
+# Fix: Terraform registry cache proxy resolves provider platforms concurrently
+
+**Date:** 2026-08-03
+
+## Summary
+
+The `Screengrabs` GitHub Actions job (run 30823640530, job 91719711270) failed on this branch
+with `context deadline exceeded` while OpenTofu queried Atmos's own Terraform Registry Cache
+proxy for `hashicorp/aws` provider metadata. Root cause: `ProviderMirror.routeVersion` resolved
+every platform a provider version advertises with one upstream HTTP call *at a time* (serially),
+and `hashicorp/aws` typically advertises 14-16 platforms — enough cumulative latency on a cold
+cache (every CI run starts cold) to exceed OpenTofu's own client-side deadline for the mirror
+request. Fixed by resolving all platforms concurrently instead of serially.
+
+## Context
+
+Atmos's Terraform Registry Cache is a local HTTPS proxy that implements the Terraform Provider
+Network Mirror Protocol, translating requests into the upstream Provider Registry Protocol
+(`pkg/terraform/registry/provider_mirror.go`, introduced in a single recent commit, #2582). To
+answer one `<version>.json` mirror request, `routeVersion` fetches the provider's full version
+list, then loops over every platform that version advertises and fetches each platform's download
+metadata (filename + hash) from the upstream registry — even though the calling client (OpenTofu)
+only ever needs the single platform it's running on. Each upstream call has a 30s timeout
+(`pkg/http/client.go`) but the loop has no aggregate ceiling, so total wall time scales with
+platform count.
+
+This was the *only* failure among the 15 most recent `Screengrabs` runs across all branches
+(including the 9 immediately prior runs on this exact branch), so it is not a deterministic bug
+that fails every time — but the architecture is a latent risk on every cold-cache run, not a pure
+random flake: any upstream latency bump, multiplied across a dozen-plus serial round-trips, can
+push total time past the client's mirror-request deadline. Confirmed by reading the code (not
+guessing) that the timeout in the log ("context deadline exceeded" on the client's own request to
+`127.0.0.1:38003`) originates from OpenTofu's provider-installer client giving up on the local
+mirror, not from Atmos's own 30s-per-call upstream timeout ever firing.
+
+## Changes
+
+- `pkg/terraform/registry/provider_mirror.go`: extracted the per-platform resolution loop out of
+  `routeVersion` into `fetchPlatformArchives`, which now fans out one goroutine per platform (via
+  `sync.WaitGroup` + a buffered results channel) instead of fetching them one at a time. Failed
+  platforms are still skipped exactly as before (a platform Terraform doesn't need is allowed to
+  fail to resolve; the one it does need surfaces on its own request). Bundled `svc`/`coord`/
+  `version` into a new `platformArchiveRequest` struct (passed by pointer) to stay within this
+  repo's `revive` argument-count and `gocritic` large-value-by-copy lint rules.
+- `pkg/terraform/registry/provider_mirror_test.go`: added
+  `TestProviderMirror_VersionResolvesPlatformsConcurrently`, a regression test using a fake
+  registry with 10 platforms each taking 150ms to resolve, asserting total wall time stays well
+  under the serial floor (10 × 150ms = 1.5s) — directly reproduces and guards against the failure
+  class that caused the CI job to fail.
+
+## Validation
+
+- Confirmed the new test fails against the pre-fix serial implementation (temporarily reverted
+  `routeVersion` to the old loop): 1.51s elapsed, correctly rejected by the `< 750ms` assertion.
+  Restored the fix and reran: 0.16s elapsed, passes.
+- `go test ./pkg/terraform/registry/... -race -count=1` — all tests pass, no data races (the
+  concurrent fetches share only a channel and a `sync.WaitGroup`; `discovery.resolve`'s cache
+  already used a mutex before this change).
+- `go build ./...` — clean.
+- `./custom-gcl run --new-from-rev=origin/main` (patch-scoped, this repo's real CI lint gate) —
+  clean on this patch after two follow-up fixes for `argument-limit` (bundled 3 params into
+  `platformArchiveRequest`) and `hugeParam` (pass that struct by pointer). One pre-existing,
+  unrelated `cyclomatic complexity` finding on `ActionForMode`
+  (`pkg/terraform/tfmigrate/tfmigrate.go`) remains, from an earlier commit this patch does not
+  touch.
+- Not yet re-run against the actual failed GitHub Actions job — this fix is uncommitted pending
+  the user's decision on whether/when to commit and push (per this repo's "never commit without
+  being asked" convention). Re-running job 91719711270 (or the workflow as a whole) after pushing
+  would confirm the fix resolves the observed failure, but since the original failure was
+  intermittent (1 in 15 recent runs), a single successful rerun cannot alone prove the fix -
+  the code-level reasoning and the new regression test are the primary evidence.
+
+## Follow-ups
+
+None.

docs/fixes/2026-08-03-tfmigrate-hooks-hard-failures.md

@@ -7,11 +7,11 @@
 Three fixes surfaced by a manual field-test pass of `atmos terraform migrate`:
 
 1. Zero-config `tfmigrate` history mode no longer crashes for a component with no `migrations/`
-   directory yet — it now prints a friendly informational message and skips invoking `tfmigrate`.
+  directory yet — it now prints a friendly informational message and skips invoking `tfmigrate`.
 2. A `kind: tfmigrate` (or any other) hook whose `kind:` value is not registered now fails hard
-   with an actionable error, instead of silently no-opping.
+  with an actionable error, instead of silently no-opping.
 3. A hook's `on_failure:` value that is not `warn`, `fail`, or `ignore` now fails hard at
-   preflight, instead of silently behaving like `warn`.
+  preflight, instead of silently behaving like `warn`.
 
 ## Context
 

pkg/terraform/registry/provider_mirror.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"net/http"
 	"strings"
+	"sync"
 
 	"github.com/cloudposse/atmos/pkg/http/proxy"
 	log "github.com/cloudposse/atmos/pkg/logger"
@@ -143,27 +144,74 @@ func (m *ProviderMirror) routeVersion(c providerCoord, version string) proxy.Rou
 				return nil, "", err
 			}
 			platforms := platformsForVersion(versions, version)
-			archives := map[string]mirrorArchive{}
-			for _, p := range platforms {
-				dlURL := fmt.Sprintf("%s%s/%s/%s/download/%s/%s", svc.providersV1, c.namespace, c.typ, version, p.OS, p.Arch)
-				dl, derr := fetchJSON[registryDownload](ctx, fetch, dlURL)
-				if derr != nil {
-					// Skip a platform that fails to resolve; the one Terraform needs surfaces in its own request.
-					log.Debug("Provider mirror: skipping platform", "provider", c.typ, "version", version, "os", p.OS, "arch", p.Arch, "error", derr)
-					continue
-				}
-				entry := mirrorArchive{URL: dl.Filename}
-				if dl.Shasum != "" {
-					entry.Hashes = []string{"zh:" + dl.Shasum}
-				}
-				archives[p.OS+"_"+p.Arch] = entry
-			}
+			archives := fetchPlatformArchives(ctx, fetch, &platformArchiveRequest{svc: svc, coord: c, version: version}, platforms)
 			b, err := json.Marshal(mirrorVersion{Archives: archives})
 			return b, contentTypeJSON, err
 		},
 	}
 }
 
+// platformArchiveRequest bundles the fields fetchPlatformArchives needs to
+// build each platform's download URL, keeping its own argument count within
+// this repo's function-argument-limit lint rule.
+type platformArchiveRequest struct {
+	svc     services
+	coord   providerCoord
+	version string
+}
+
+// platformArchiveResult pairs a resolved platform's mirror key with its
+// archive entry, or reports that the platform failed to resolve and should
+// be skipped.
+type platformArchiveResult struct {
+	key   string
+	entry mirrorArchive
+	ok    bool
+}
+
+// fetchPlatformArchives resolves every platform's download metadata
+// concurrently. A provider version can advertise a dozen or more platforms;
+// resolving them one upstream round-trip at a time on a cold cache (every CI
+// run starts cold) can add up to tens of seconds of cumulative latency,
+// risking the client's own mirror-request deadline even though the client
+// only ever needs a single platform's entry. Fetching them in parallel bounds
+// the wall time to roughly one round-trip instead of platform-count round-trips.
+func fetchPlatformArchives(ctx context.Context, fetch proxy.Fetcher, req *platformArchiveRequest, platforms []registryPlatform) map[string]mirrorArchive {
+	results := make(chan platformArchiveResult, len(platforms))
+	var wg sync.WaitGroup
+	for _, p := range platforms {
+		wg.Add(1)
+		go func(p registryPlatform) {
+			defer wg.Done()
+			dlURL := fmt.Sprintf("%s%s/%s/%s/download/%s/%s", req.svc.providersV1, req.coord.namespace, req.coord.typ, req.version, p.OS, p.Arch)
+			dl, err := fetchJSON[registryDownload](ctx, fetch, dlURL)
+			if err != nil {
+				// Skip a platform that fails to resolve; the one Terraform needs surfaces in its own request.
+				log.Debug("Provider mirror: skipping platform", "provider", req.coord.typ, "version", req.version, "os", p.OS, "arch", p.Arch, "error", err)
+				results <- platformArchiveResult{}
+				return
+			}
+			entry := mirrorArchive{URL: dl.Filename}
+			if dl.Shasum != "" {
+				entry.Hashes = []string{"zh:" + dl.Shasum}
+			}
+			results <- platformArchiveResult{key: p.OS + "_" + p.Arch, entry: entry, ok: true}
+		}(p)
+	}
+	go func() {
+		wg.Wait()
+		close(results)
+	}()
+
+	archives := make(map[string]mirrorArchive, len(platforms))
+	for r := range results {
+		if r.ok {
+			archives[r.key] = r.entry
+		}
+	}
+	return archives
+}
+
 // registryPlatform is a single os/arch a provider version supports.
 type registryPlatform struct {
 	OS   string

pkg/terraform/registry/provider_mirror_test.go

@@ -4,10 +4,12 @@ import (
 	"crypto/sha256"
 	"encoding/hex"
 	"encoding/json"
+	"fmt"
 	"net/http"
 	"net/http/httptest"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -123,6 +125,73 @@ func TestProviderMirror_VersionListsAllPlatforms(t *testing.T) {
 	assert.Equal(t, []string{"zh:" + fr.zipSum}, ver.Archives["linux_amd64"].Hashes)
 }
 
+// TestProviderMirror_VersionResolvesPlatformsConcurrently guards against a
+// regression to serial per-platform resolution (the root cause of a CI
+// screengrab failure: OpenTofu's own mirror-request deadline was exceeded
+// because a cold-cache version fetch resolved a dozen-plus platforms one
+// upstream round-trip at a time). With N platforms each taking `delay` to
+// resolve, a serial implementation takes at least N*delay; a concurrent one
+// takes roughly one delay regardless of N.
+func TestProviderMirror_VersionResolvesPlatformsConcurrently(t *testing.T) {
+	const (
+		platformCount = 10
+		delay         = 150 * time.Millisecond
+	)
+
+	platforms := make([]struct {
+		OS   string `json:"os"`
+		Arch string `json:"arch"`
+	}, platformCount)
+	for i := range platforms {
+		platforms[i].OS = fmt.Sprintf("os%d", i)
+		platforms[i].Arch = "amd64"
+	}
+	platformsJSON, err := json.Marshal(platforms)
+	require.NoError(t, err)
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/.well-known/terraform.json", func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte(`{"providers.v1":"/v1/providers/","modules.v1":"/v1/modules/"}`))
+	})
+	mux.HandleFunc("/v1/providers/hashicorp/aws/versions", func(w http.ResponseWriter, r *http.Request) {
+		_, _ = fmt.Fprintf(w, `{"versions":[{"version":"5.95.0","platforms":%s}]}`, platformsJSON)
+	})
+	mux.HandleFunc("/v1/providers/hashicorp/aws/5.95.0/download/", func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(delay)
+		seg := strings.Split(strings.TrimPrefix(r.URL.Path, "/v1/providers/hashicorp/aws/5.95.0/download/"), "/")
+		osName, arch := seg[0], seg[1]
+		resp := registryDownload{
+			Filename: "terraform-provider-aws_5.95.0_" + osName + "_" + arch + ".zip",
+		}
+		_ = json.NewEncoder(w).Encode(resp)
+	})
+	server := httptest.NewServer(mux)
+	t.Cleanup(server.Close)
+
+	client := &hostRewriteClient{target: server.URL, host: "registry.terraform.io"}
+	srv := proxy.NewServer(proxy.Options{
+		Mirrors: []proxy.Mirror{NewProviderMirror(client)},
+		Store:   proxy.NewFileStore(t.TempDir()),
+		Client:  client,
+	})
+	_, err = srv.Start(t.Context())
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = srv.Shutdown(t.Context()) })
+
+	start := time.Now()
+	body := mustGet(t, srv.BaseURL()+"providers/registry.terraform.io/hashicorp/aws/5.95.0.json")
+	elapsed := time.Since(start)
+
+	var ver mirrorVersion
+	require.NoError(t, json.Unmarshal(body, &ver))
+	assert.Len(t, ver.Archives, platformCount, "all platforms should resolve")
+
+	serialFloor := time.Duration(platformCount) * delay
+	assert.Less(t, elapsed, serialFloor/2,
+		"resolving %d platforms took %s - expected well under the %s serial floor, indicating platforms are fetched concurrently, not one at a time",
+		platformCount, elapsed, serialFloor)
+}
+
 func TestProviderMirror_ArchiveDownloadAndVerify(t *testing.T) {
 	fr := newFakeRegistry(t)
 	srv := startProviderProxy(t, fr)