engsys 1.0.0

package/stacks/cloud/cloudflare/skills/cloudflare-deployment-preflight/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: cloudflare-deployment-preflight
+description: Preflight validation for Cloudflare Workers/Pages deployments via Wrangler. Run before any wrangler deploy. Dry-run builds (wrangler deploy --dry-run), gradual rollout via versions upload + deployments, secrets via wrangler secret, D1 migrations (wrangler d1 migrations), account/auth check (wrangler whoami), bindings correctness in wrangler.toml (vars/KV/R2/D1/Durable Objects/Queues), and wrangler tail for logs. Activate when the active cloud is Cloudflare and the user mentions deploying a Worker/Pages, validating wrangler config, gradual rollout, secrets, D1 migrations, bindings, or preparing for wrangler deploy.
+---
+
+# Cloudflare Deployment Preflight
+
+The Cloudflare analogue of pre-deploy validation: build and validate locally, confirm the
+target account and bindings, and stage the rollout *before* you push live, so users don't
+discover what you could have caught. Works for Workers and Pages (both run on Wrangler).
+Continue through all steps even if one fails — capture every issue, then fix them in a
+batch.
+
+> Discipline: **batch your fixes.** A Worker `deploy` is global within seconds — there's no
+> per-region canary by default. Read the whole config, reason about every issue, fix them
+> all, then deploy once behind a gradual rollout. One staged rollout, not one deploy per
+> error.
+
+## When to use
+
+- Before `wrangler deploy` / `wrangler versions upload` / `wrangler pages deploy`.
+- When preparing or reviewing `wrangler.toml` (bindings, vars, compatibility settings).
+- To preview what a deploy will produce (`--dry-run`).
+- Before running D1 migrations against a production database.
+- When a deploy "worked locally" but the live Worker errors on a missing binding/secret.
+
+## Step 1 — Confirm the target account & auth
+
+Deploying to the wrong account is the most expensive mistake. Wrangler picks up auth from
+`wrangler login` (OAuth) or a `CLOUDFLARE_API_TOKEN` env var, and the account from
+`account_id` in `wrangler.toml` or `CLOUDFLARE_ACCOUNT_ID`.
+
+```bash
+wrangler whoami            # who am I, and which account(s) can I deploy to?
+```
+
+Confirm the printed account matches the intended one and that the token has the needed
+scopes (Workers Scripts, D1, R2, KV, etc.). If `whoami` shows multiple accounts, pin
+`account_id` in `wrangler.toml` so a deploy can't silently land in the wrong account.
+
+## Step 2 — Dry-run the build
+
+`--dry-run` runs the full bundle + binding resolution **without uploading anything** — it
+catches build errors, missing modules, oversized bundles, and (with `--outdir`) lets you
+inspect the output.
+
+```bash
+# Build + validate, upload NOTHING. The core preflight.
+wrangler deploy --dry-run --outdir dist/
+
+# Pages equivalent: build locally and inspect, no deploy
+wrangler pages functions build        # builds Functions to inspect
+```
+
+This is the equivalent of `cdk synth` / `bicep build` / `terraform plan`'s build half —
+it will **not** catch a binding that exists in config but not in the account (a KV
+namespace / D1 / R2 bucket that was never created), or a missing secret. Those are Steps
+3–4. Watch the reported **bundle size** against the plan limit (3MB Free / 10MB paid).
+
+## Step 3 — Validate bindings in wrangler.toml
+
+The #1 cause of "works in dev, 1101/exception in prod" is a binding that's declared but the
+underlying resource doesn't exist, or an ID mismatch. Cross-check every binding in
+`wrangler.toml` against what actually exists in the account:
+
+| Binding | wrangler.toml | Verify the resource exists |
+| --- | --- | --- |
+| **Vars** (plaintext) | `[vars]` | non-secret config only — never put secrets here |
+| **KV** | `[[kv_namespaces]]` `id` | `wrangler kv namespace list` |
+| **R2** | `[[r2_buckets]]` `bucket_name` | `wrangler r2 bucket list` |
+| **D1** | `[[d1_databases]]` `database_id` | `wrangler d1 list` / `wrangler d1 info <db>` |
+| **Durable Objects** | `[[durable_objects.bindings]]` + `[[migrations]]` | DO classes need a migration tag (see Step 5) |
+| **Queues** | `[[queues.producers]]` / `[[queues.consumers]]` | `wrangler queues list` |
+| **Service bindings** | `[[services]]` | the target Worker must be deployed |
+
+```bash
+wrangler kv namespace list        # IDs must match [[kv_namespaces]].id
+wrangler r2 bucket list           # names must match [[r2_buckets]].bucket_name
+wrangler d1 list                  # D1 databases + their IDs
+wrangler d1 info <db-name>        # size, region, details for one D1
+wrangler queues list              # queues must exist before a consumer deploys
+```
+
+A mismatched `id`/`name`, or a `binding` name the code references that isn't in the toml,
+is a runtime exception, not a build error — `--dry-run` won't catch it. Confirm the
+`compatibility_date` and any `compatibility_flags` (e.g. `nodejs_compat`) are set, since a
+stale compat date can change runtime behavior.
+
+## Step 4 — Secrets (never in wrangler.toml)
+
+Secrets are set out-of-band and are **not** in `wrangler.toml` (only non-secret `[vars]`
+go there). A Worker that reads `env.MY_SECRET` will get `undefined` and throw if the secret
+was never uploaded to that environment.
+
+```bash
+wrangler secret list                      # which secrets exist for this Worker/env
+wrangler secret put MY_SECRET             # set (prompts for value) — MUTATING, gated
+wrangler secret put MY_SECRET --env prod  # per-environment
+```
+
+Preflight: `wrangler secret list` and confirm every secret the code reads is present for
+the target environment. Setting secrets (`secret put`) is a mutating action — do it
+deliberately, per environment, not as part of casual inspection.
+
+## Step 5 — D1 migrations
+
+D1 schema changes go through Wrangler's migration system. Apply to **local first, then a
+remote staging DB, then production** — never run an unreviewed migration straight at prod.
+
+```bash
+wrangler d1 migrations create <db> <name>   # scaffold a new migration file
+wrangler d1 migrations list <db>            # which migrations are applied vs pending
+wrangler d1 migrations list <db> --remote   # against the real remote DB
+wrangler d1 migrations apply <db> --local   # apply locally first
+wrangler d1 migrations apply <db> --remote  # apply to remote — MUTATING, gated
+```
+
+> `migrations list` is read-only (safe preflight — see exactly what's pending). `apply`
+> and any `d1 execute` are mutating and gated. Remember D1 is **SQLite** with a **10GB
+> ceiling** and primary-region writes — a migration that rewrites a large table can be slow
+> and bills `rows_written`. Review the SQL; back up / export if it's destructive.
+
+## Step 6 — Stage the rollout (versions + gradual deployment)
+
+`wrangler deploy` publishes **globally within seconds** with no built-in canary. For
+anything risky, use the **versions** workflow to upload a version without serving it, then
+ramp traffic gradually and roll back instantly if metrics turn.
+
+```bash
+# Upload a new version WITHOUT routing any traffic to it
+wrangler versions upload
+
+wrangler versions list                  # see versions + which is serving
+wrangler versions view <version-id>     # inspect one
+
+# Roll out gradually: split traffic across versions (e.g. 10% new / 90% old)
+wrangler versions deploy                # interactive percentage split
+
+# Watch the new version under real traffic, then ramp to 100% — or roll back
+# by deploying 100% of the previous version.
+```
+
+This is the Cloudflare answer to a canary / change set: ship the version, point a slice of
+production at it, watch `wrangler tail` + analytics, then complete or revert. Far safer
+than a bare `wrangler deploy` for a change touching a hot path.
+
+## Step 7 — Verify after rollout (tail the logs)
+
+Once a version is taking traffic, watch live requests for new exceptions before ramping to
+100%:
+
+```bash
+wrangler tail                                   # live request log stream
+wrangler tail --status error                    # only errored invocations
+wrangler tail --format json | jq '.exceptions'  # structured, filter exceptions
+```
+
+Look for `Exceeded CPU`/`Exceeded Memory` (1102), subrequest-limit errors, missing-binding
+exceptions, and elevated 5xx/exception rate on the new version. If clean, complete the
+rollout; if not, roll back to the prior version immediately.
+
+## Step 8 — Report
+
+Summarize: account confirmed (`whoami`), dry-run build result + bundle size vs limit,
+binding/resource cross-check (every KV/R2/D1/DO/Queue binding resolved to a real resource),
+secrets present for the target env, D1 migrations pending/applied, and the rollout plan
+(version id, traffic split, rollback path). Flag any **destructive D1 migration**, any
+**missing binding or secret**, and any **bundle over the plan limit**. State clearly whether
+it's safe to deploy and at what initial traffic percentage.
+
+## Tool requirements
+
+`wrangler` CLI (v3+), authenticated via `wrangler login` or `CLOUDFLARE_API_TOKEN`. Verify
+auth + account first: `wrangler whoami`. `jq` optional for parsing `wrangler tail --format
+json`.

package/stacks/cloud/gcp/claude.fragment.md

@@ -0,0 +1,17 @@
+## Cloud stack
+
+- **Active cloud: GCP.** Architecture and IaC target Google Cloud; agents load the
+  `cloud-architecture-gcp` and `gcp-deployment-preflight` skill packs.
+- **Tool preference order** (when investigating or validating cloud state):
+  1. **gcloud / gsutil, read-only** — `gcloud config get-value project`,
+     `gcloud auth list`, `gcloud run services list`, `gcloud sql instances describe`,
+     `gcloud logging read`, `gcloud compute regions describe`,
+     `gcloud services list --enabled`, `gsutil ls` and similar inspection commands.
+     Never mutate state to answer a question.
+  2. **Docs source** — official Google Cloud documentation (cloud.google.com/docs) for
+     quotas, pricing, and API behavior. Verify against docs rather than from memory.
+- Mutating actions (deploy/apply/delete) go through the IaC tool and the
+  `gcp-deployment-preflight` gate, never ad-hoc CLI writes.
+
+<!-- naturalize: confirm the GCP project ID(s), region(s), and the path to the
+architecture/cost docs Melvin and Aaron should read for concrete topology. -->

package/stacks/cloud/gcp/settings.fragment.json

@@ -0,0 +1,40 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(gcloud config get-value:*)",
+      "Bash(gcloud auth list:*)",
+      "Bash(gcloud projects list:*)",
+      "Bash(gcloud projects describe:*)",
+      "Bash(gcloud services list:*)",
+      "Bash(gcloud run services list:*)",
+      "Bash(gcloud run services describe:*)",
+      "Bash(gcloud run revisions list:*)",
+      "Bash(gcloud sql instances list:*)",
+      "Bash(gcloud sql instances describe:*)",
+      "Bash(gcloud pubsub topics list:*)",
+      "Bash(gcloud pubsub subscriptions describe:*)",
+      "Bash(gcloud compute regions describe:*)",
+      "Bash(gcloud compute project-info describe:*)",
+      "Bash(gcloud artifacts repositories describe:*)",
+      "Bash(gcloud deployment-manager deployments list:*)",
+      "Bash(gcloud deployment-manager deployments describe:*)",
+      "Bash(gcloud deployment-manager operations list:*)",
+      "Bash(gcloud logging read:*)",
+      "Bash(gsutil ls:*)",
+      "Bash(terraform fmt:*)",
+      "Bash(terraform validate:*)",
+      "Bash(terraform plan:*)",
+      "Bash(terraform show:*)"
+    ],
+    "deny": [
+      "Bash(gcloud run deploy:*)",
+      "Bash(gcloud sql instances delete:*)",
+      "Bash(gcloud deployment-manager deployments create:*)",
+      "Bash(gcloud deployment-manager deployments update:*)",
+      "Bash(gcloud deployment-manager deployments delete:*)",
+      "Bash(terraform apply:*)",
+      "Bash(terraform destroy:*)"
+    ]
+  },
+  "mcpServers": {}
+}

package/stacks/cloud/gcp/skills/cloud-architecture-gcp/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: cloud-architecture-gcp
+description: GCP service-level architecture knowledge — compute (Cloud Run/GKE/Cloud Functions/GCE), data (Cloud SQL/Spanner/Firestore/Bigtable), messaging (Pub/Sub/Cloud Tasks/Workflows), analytics (BigQuery), edge (Cloud CDN/Load Balancing/API Gateway), storage + secrets (GCS/Secret Manager/Artifact Registry), and Vertex AI. Cost models, quotas, failure modes, and cold-start gotchas. Activate when the active cloud is GCP and the work involves designing, scaling, costing, or diagnosing GCP architecture (Cloud Run cold starts, Cloud SQL connection limits, Spanner hot spots, egress, Pub/Sub backlog).
+---
+
+# GCP Architecture Knowledge
+
+Service-level detail for a GCP-backed project. Pairs with Melvin's cloud-agnostic
+diagnostic checklist (traffic pattern, state location, SLAs, blast radius, cost
+explosion, coordination, limits, observability) — this pack supplies the GCP-specific
+answers. For concrete topology, cost tiers, and stack context, read the architecture
+docs named in `CLAUDE.md`.
+
+## Compute
+
+### Cloud Run
+
+- Serverless containers, request- or instance-billed, **scales to zero**. The
+  cost win and the latency trap: a scaled-to-zero service pays a **cold start** (image
+  pull + container start) on the next request. Set **`min-instances >= 1`** to keep a
+  warm instance for latency-sensitive paths — the Cloud Run analogue of provisioned
+  concurrency.
+- **Concurrency:** one Cloud Run instance serves *multiple* concurrent requests
+  (default up to 80, tunable) — unlike Lambda's one-request-per-instance. Right concurrency
+  setting massively affects cost and tail latency; CPU-bound work wants lower concurrency,
+  IO-bound can go higher. `--cpu-throttling` (CPU only during requests) vs always-on CPU
+  (for background work) is a real cost lever.
+- **Limits:** per-service max instances (set it to cap blast radius and spend), request
+  timeout up to 60 min, memory/CPU per instance. Cloud Run **jobs** for run-to-completion
+  batch (vs services for request serving).
+- **Good for:** HTTP APIs, event consumers (Eventarc/Pub/Sub push), web apps. Prefer it
+  over GKE unless you need Kubernetes primitives.
+
+### GKE
+
+- Managed Kubernetes. **Autopilot** (Google manages nodes, pay per pod resource — less
+  ops, good default) vs **Standard** (you manage node pools — more control, GPUs, custom
+  scheduling). Reach for GKE only when you need the K8s ecosystem (operators, mesh,
+  complex scheduling, multi-tenant platform); otherwise Cloud Run is far less overhead.
+
+### Cloud Functions
+
+- Event-driven serverless (2nd gen runs on Cloud Run + Eventarc under the hood — same
+  cold-start and concurrency model). Triggers: HTTP, Pub/Sub, GCS, Firestore, Eventarc.
+  Good for glue and event handlers; for sustained or latency-critical work, Cloud Run
+  with min-instances.
+
+### Compute Engine (GCE)
+
+- VMs: any machine type (general/compute/memory/GPU/TPU), **Spot/Preemptible** for
+  fault-tolerant batch (deep discount, can be reclaimed), **Committed Use Discounts**
+  (1/3-yr) and Sustained Use Discounts for steady baseline. The escape hatch when
+  managed compute can't meet a hardware/licensing/latency need.
+
+## Data
+
+### Cloud SQL (PostgreSQL / MySQL)
+
+- Managed relational. **Connection limits** scale with tier and are the classic
+  bottleneck — serverless/many-instance apps exhaust them. Use the **Cloud SQL Auth
+  Proxy** + a pooler (PgBouncer) or built-in connection pooling; serverless callers
+  should pool aggressively. HA = regional (synchronous standby; failover drops
+  connections — apps must reconnect/retry). Read replicas scale reads, not writes.
+- IOPS/throughput scale with disk size and tier; watch on write-heavy workloads. Right-
+  size the tier from metrics, don't over-provision.
+
+### Spanner
+
+- Horizontally-scalable, strongly-consistent relational (global). **Schema / primary-key
+  design is everything** — monotonically increasing keys (timestamps, sequential IDs)
+  create **hot spots** on one split; use hashed/UUID or bit-reversed keys for even
+  distribution. Billed by **node/processing-unit + storage**; not cheap — justify it
+  with genuine horizontal-scale or global-consistency needs over Cloud SQL.
+
+### Firestore
+
+- Serverless document DB, auto-scaling, real-time listeners. Strong consistency,
+  multi-region options. **Cost is per-operation** (reads/writes/deletes) + storage —
+  read-heavy fan-out and unbounded queries get expensive; **avoid N+1 read patterns**
+  and design for composite indexes. Great for app/user data with realtime needs.
+
+### Bigtable
+
+- Wide-column NoSQL for massive scale + low-latency (time-series, IoT, analytics
+  serving). **Row-key design is everything** — sequential keys hot-spot a single node;
+  design for even distribution. Billed per node + storage. Reach for it at very high
+  throughput where Firestore/Spanner don't fit.
+
+## Messaging & Orchestration
+
+### Pub/Sub
+
+- Global, auto-scaling messaging. **Push** (delivers to an endpoint — Cloud Run/Functions)
+  vs **pull** (consumer fetches). At-least-once delivery → **idempotent consumers
+  required**; **ordering keys** for ordered delivery (lower throughput per key).
+- Configure **ack deadline** > processing time or you get redelivery, and a **dead-letter
+  topic** with max delivery attempts for poison messages. Subscription **backlog**
+  (`num_undelivered_messages` / oldest-unacked-age) is the metric that predicts pain.
+- **Pub/Sub Lite** is a cheaper, zonal, capacity-provisioned variant for high-volume
+  cost-sensitive streaming — fewer features, you manage capacity.
+
+### Cloud Tasks / Workflows
+
+- **Cloud Tasks:** managed task queues with rate limiting + scheduled/deferred dispatch
+  to HTTP targets — good for decoupling and controlled throughput to a downstream.
+- **Workflows:** serverless orchestration (YAML/JSON) of service calls with retries,
+  error handling, and parallel steps — the explicit-state-machine option (vs hiding
+  coordination in code). **Eventarc** routes events (GCS, Pub/Sub, audit logs) to Cloud
+  Run/Functions/Workflows.
+
+## Analytics
+
+### BigQuery
+
+- Serverless data warehouse. **Two pricing models:** **on-demand** (per TB *scanned* —
+  a `SELECT *` or unpartitioned full scan is a budget event) vs **capacity/slots**
+  (reserved compute, predictable). Control cost with **partitioning + clustering**,
+  selecting only needed columns, and `--maximum-bytes-billed` guards. Streaming inserts
+  and storage are separate line items. Not an OLTP store — it's analytics.
+
+## Edge & Networking
+
+### Cloud Load Balancing + Cloud CDN
+
+- Global external HTTP(S) load balancer (Anycast, single global IP) with **Cloud CDN**
+  edge caching and **Cloud Armor** WAF/DDoS. Cache key + TTL design drive hit ratio.
+  Use it for global entry, edge caching, and WAF.
+
+### API Gateway / Apigee
+
+- **API Gateway** (lightweight, managed, for serverless backends) vs **Apigee** (full
+  enterprise API management — policies, monetization, developer portal; heavier and
+  pricier). Pick by how much API-management you actually need.
+
+### VPC / Networking — cost landmines
+
+- **Cloud NAT** for egress from private instances (per-GB + hourly), and **egress data
+  transfer** — inter-zone, inter-region, and internet egress are all per-GB (internet
+  and cross-region the most). Use **Private Google Access** / **Private Service Connect**
+  to reach Google APIs/services without public egress, and **VPC Service Controls** for
+  data-exfil boundaries. Default to private; public only where required.
+
+## Storage, Secrets & Registry
+
+### Cloud Storage (GCS)
+
+- Object storage. Classes: Standard → Nearline → Coldline → Archive (retrieval cost +
+  minimum storage duration). Lifecycle rules to age data down. **Globally-unique bucket
+  names** (see preflight). Cost = storage + **operations** (per-1000 Class A/B) + egress.
+  Uniform bucket-level access + IAM; encryption at rest by default (CMEK via Cloud KMS).
+
+### Secret Manager
+
+- Versioned secrets with IAM access control; reference from Cloud Run/Functions as
+  mounted secrets or env. Keep secrets out of images and config. Pair with **Workload
+  Identity** so services authenticate without long-lived keys.
+
+### Artifact Registry
+
+- Container images + language packages (successor to Container Registry). Use Workload
+  Identity / service-account auth for pulls; regional repos to avoid cross-region pull
+  egress.
+
+## Vertex AI
+
+- Managed ML + GenAI: **Model Garden** (Gemini, plus third-party and open models),
+  online **prediction endpoints** (deploy a model behind an autoscaling endpoint — set
+  min replicas to avoid cold start, max to cap cost), batch prediction, training
+  pipelines, **Vector Search** for managed RAG.
+- **Quotas matter:** per-model/region requests-per-minute and tokens-per-minute (or QPM)
+  limits will throttle a naive high-volume pipeline — request increases early and add
+  backoff. Provisioned Throughput for guaranteed capacity (committed spend). Cost is
+  token/prediction-driven; model availability varies by region. Right-size the model per
+  task.
+
+## Cost realism (where GCP bills explode)
+
+1. **Egress** — internet + cross-region + inter-zone data transfer, per-GB.
+2. **Cloud NAT** — per-GB processing + hourly. Use Private Google Access / PSC.
+3. **BigQuery on-demand scans** — per-TB; partition/cluster and limit columns.
+4. **Cloud Run / GKE over-provisioning** — instance-seconds on idle min-instances /
+   always-on CPU; over-large GKE node pools.
+5. **Spanner / Bigtable nodes** — billed even when idle.
+6. **Firestore operations** — per read/write at high fan-out.
+7. **Vertex AI tokens / always-on endpoints**.
+
+Levers: Committed Use Discounts + Sustained Use Discounts (steady baseline), Spot/
+Preemptible (fault-tolerant batch), right-sizing from Cloud Monitoring, Private Google
+Access, GCS lifecycle tiering, BigQuery partitioning + `maximum-bytes-billed`, budgets +
+alerts.
+
+## Quotas (request increases *before* they bite)
+
+Per-project/region: Compute CPUs + GPUs/TPUs per family, in-use external IPs, Cloud Run
+max instances + CPU quota, Cloud Functions instances, Cloud SQL connections + instances,
+Spanner nodes, Pub/Sub publish/throughput, BigQuery concurrent queries + slots, Vertex
+AI per-model RPM/TPM, GCS request rate. Many are soft (raise via IAM & Admin → Quotas
+with lead time); some are hard. Check `gcloud compute regions describe` / the Quotas page
+and plan around the hard ones.
+
+## Observability
+
+Cloud **Operations Suite**: Cloud Monitoring (metrics + alerting policies), Cloud Logging
+(Log Explorer + log-based metrics), Cloud Trace (distributed tracing), Error Reporting,
+Profiler. Alert on the predictors of pain: Cloud Run instance count + request latency p99
++ container startup, Pub/Sub subscription backlog + oldest-unacked-age, Cloud SQL
+connections + CPU + replica lag, Spanner CPU + hot-split, BigQuery bytes-billed,
+Cloud NAT allocation/dropped connections.

package/stacks/cloud/gcp/skills/gcp-deployment-preflight/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: gcp-deployment-preflight
+description: Preflight validation for GCP infrastructure deployments (Terraform / gcloud / Deployment Manager / Config Connector). Run before any deploy. Validates templates (terraform validate/plan or gcloud deployment preview), cleans up stale/failed deployments and stuck resources, catches globally-unique naming conflicts (GCS bucket, project IDs, Artifact Registry), and checks quota/capacity limits. Activate when the active cloud is GCP and the user mentions deploying, validating, previewing infra changes, gcloud deploy, terraform plan/apply on GCP, or deploy failures.
+---
+
+# GCP Deployment Preflight
+
+Validate GCP infrastructure changes locally and clear blocking state *before* you
+deploy, so CI doesn't discover what you could have caught. Continue through all steps
+even if one fails — capture every issue, then fix them in a batch.
+
+> Discipline: **batch your fixes.** Each deploy/CI run costs real minutes. Read the
+> whole failing config, reason about every issue, fix them all, push once. One run per
+> problem cluster, not one per error message.
+
+## When to use
+
+- Before `terraform apply`, `gcloud run deploy`, `gcloud deployment-manager deployments
+  create/update`, or Config Connector / KCC applies.
+- When preparing or reviewing GCP IaC (Terraform google provider, Deployment Manager,
+  Config Connector manifests).
+- To preview what a deploy will change.
+- After a failed deploy left a deployment or resource stuck.
+
+## Step 1 — Detect project type & confirm context
+
+- **Terraform (most common for GCP IaC):** `*.tf` with the `google`/`google-beta`
+  provider, backend in GCS. → use the Terraform flow (Step 2a).
+- **gcloud / Deployment Manager:** `*.yaml`/`*.jinja` DM configs, or imperative
+  `gcloud` deploys. → Step 2b.
+- **Config Connector / KCC:** Kubernetes-style GCP-resource manifests applied to a
+  cluster.
+- Confirm context — wrong project is the expensive mistake:
+
+```bash
+gcloud config get-value project
+gcloud auth list                       # active account
+gcloud config get-value compute/region
+```
+
+## Step 2 — Validate & preview
+
+### 2a — Terraform
+
+```bash
+terraform fmt -check
+terraform validate
+terraform plan -out=tfplan             # the what-if; review creates/changes/destroys
+terraform show -no-color tfplan        # inspect details
+```
+
+Review the plan for **destroys / replacements of stateful resources** (Cloud SQL,
+Spanner, GCS buckets, persistent disks) and any IAM-binding changes. Never rubber-stamp
+a replacement of a data store.
+
+### 2b — gcloud / Deployment Manager
+
+```bash
+# Deployment Manager dry-run preview
+gcloud deployment-manager deployments update <name> --config config.yaml --preview
+gcloud deployment-manager deployments describe <name>     # inspect the preview
+
+# Cloud Run: validate the service spec without serving traffic
+gcloud run deploy <svc> --image <img> --no-traffic --tag preflight  # revision w/o traffic
+```
+
+## Step 3 — Clean up stale / failed deployments & stuck resources
+
+```bash
+# Deployment Manager: failed deployments block re-create
+gcloud deployment-manager deployments list \
+  --filter="operation.status!=DONE OR operation.error:*"
+gcloud deployment-manager deployments delete <name>        # if stuck/failed
+
+# Recent failed operations (root cause — read the first error, not the cascade)
+gcloud logging read 'severity>=ERROR' --limit 20 --freshness=1h
+```
+
+Terraform: a partial apply leaves real resources with no/partial state. Use
+`terraform state list` + `terraform import` to reconcile, or `-target` a clean re-apply.
+Watch for **resources that block deletion** — non-empty GCS buckets, Artifact Registry
+repos with images, resources with `deletion_protection = true` (Cloud SQL, Spanner),
+in-use IPs/networks. Clear them first.
+
+## Step 4 — Globally-unique naming conflicts
+
+| Resource | Namespace | Conflict mode |
+| --- | --- | --- |
+| **GCS bucket** | Global (all of GCP) | name taken / recently-deleted names reserved |
+| **Project ID** | Global, **immutable**, not reusable | must be unique forever |
+| **Artifact Registry repo** | Per project+location | already-exists |
+| Cloud Run service, Pub/Sub topic, etc. | Per project (+region) | recreate collisions after partial deploys |
+
+**Pattern:** never hard-code a globally-unique name — add a short unique suffix
+(project-id fragment / random) via a Terraform variable or `random_id`, and check
+availability before deploy (`gsutil ls -b gs://<name>` / `gcloud artifacts repositories
+describe`). Project IDs especially are permanent — pick deliberately.
+
+## Step 5 — Quota & capacity check
+
+Deploys fail late when a quota is hit. Pre-check what the change will consume:
+
+```bash
+gcloud compute regions describe <region> \
+  --format="table(quotas.metric, quotas.limit, quotas.usage)"
+gcloud compute project-info describe \
+  --format="table(quotas.metric, quotas.limit, quotas.usage)"
+```
+
+Common deploy-blocking quotas: Compute CPUs / in-use external IPs per region, GPUs/TPUs,
+Cloud Run CPU + max-instances quota, Cloud SQL instances, Spanner nodes, VPC networks/
+subnets, and **API enablement** — a deploy fails if the required API isn't enabled
+(`gcloud services list --enabled`; enable with `gcloud services enable`). Soft quotas
+need an IAM & Admin → Quotas request with lead time — raise them before the deploy.
+
+## Step 6 — Check for an in-flight deploy before triggering
+
+If CI auto-deploys on push, don't fire a manual deploy on top — the runs race.
+
+```bash
+gh run list --workflow="<deploy workflow>" --limit 3
+gcloud deployment-manager operations list --filter="status!=DONE"
+```
+
+If a deploy is in progress, wait.
+
+## Step 7 — Report
+
+Summarize: validate/plan results (creates / modifies / **destroys** / replacements),
+deployments cleaned up, naming overrides applied, required-API + quota headroom, and
+whether it's safe to deploy. Flag any replacement of a stateful resource and any IAM
+change.
+
+## Tool requirements
+
+`gcloud` CLI, `terraform` (for TF projects), `gsutil`, `gh` (if CI-driven). Verify auth:
+`gcloud auth list` / `gcloud config get-value project`.