devops-infra-helm-charts-gcp/docs/global/AGENT_BOUNDARIES.md

AGENT_BOUNDARIES.md

Scope: operations agents may perform on the devops-infra-helm-charts repo. Companion docs: SANCTITY_RULES.md (hard rules), coding-guidelines/helm-values.md (style).

This document classifies every operation in this repo into Layer 1 / 2 / 3 with explicit blast radius and approval requirements. An agent operating in this repo MUST consult this file before any write.

---

The 3-Layer Model (recap)

Layer	Agent action	Safety gate
Layer 1 — Agent-Writable	Generate diff, open PR. Do not apply directly to clusters.	PR review + Argo CD UI Sync click.
Layer 2 — Agent-Readable (Advisory)	Research, analyse, recommend. Human executes.	Human review + manual execution.
Layer 3 — Agent-Blocked	Refuse the write. Explain why. Cite this doc.	None applicable.

---

Per-operation classification

Layer 1 — Agent-Writable (this repo's normal operating range)

All edits land via PR. A merge to main is then reconciled by Argo CD per cluster — most infra Applications use manual sync (ADR-A5), so the workload deploy is a separate human Sync click.

Operation	File(s) touched	Blast radius	Required approvers
Edit custom-values.yaml for one app on one cluster	helm-overrides/<cluster>/<app>/custom-values.yaml	One Helm release on one cluster	Service / app owner
Add a new app under an existing cluster	new dir + files in helm-overrides/<cluster>/<app>/	One new release	App owner + cluster owner; pair with Argo Application PR in sister repo
Add a sidecar raw manifest alongside an existing app	helm-overrides/<cluster>/<app>/<extra>.yaml	Adds Kubernetes resources rendered alongside the Helm release	App owner
Add a new override file under an existing app dir	new file in helm-overrides/<cluster>/<app>/	Layered into the same release if the Argo Application's valueFiles covers it	App owner
Append to an existing chart's Chart.yaml dependencies[]	helm-templates/<chart>/Chart.yaml + refresh Chart.lock via helm dependency update	Affects every consumer of that chart	Platform team
Bump a dependencies[].version in Chart.yaml	helm-templates/<chart>/Chart.yaml + Chart.lock	Same	Platform team — see update-chart-version
Add a new chart sibling for blue-green migration	new dir helm-templates/<chart>-<variant>/	Migration target only; old sibling stays live	Platform team — see blue-green-chart-migration
Edit the per-cluster Contour scheduling matrix	contour-nodeselector-tolerations-summary.md	Documentation; no runtime effect	Platform team

Layer 1 — HIGH RISK (write allowed, but require explicit approval and detailed rationale in PR)

Operation	Why it's high risk
Edit helm-templates/<chart>/templates/ or helm-templates/<chart>/values.yaml	Most charts here are vanilla upstream pulled via helm pull. Edits silently fork the chart and get clobbered on the next upstream sync. Only allowed if the fork is intentional and documented in that chart's README.md — see fork-upstream-chart.
Delete a versioned sibling chart (<chart>-green, <chart>-vX.Y.Z, <chart>-latest, <chart>-old)	The variant is a blue-green migration target. Both versions may be live simultaneously. Confirm zero references in github.com/Meesho/devops-infra-argo-config before deleting.
Edit manifests/storageclass/*.yaml	Cluster-wide singleton; affects every PVC. Platform-team review required.
Edit manifests/priorityclass/<cluster>/*.yaml	Affects scheduling priority for every pod that references the class. Platform-team review.
Edit manifests/{jenkins-filestore-caching,jenkins-gcs-caching,jfrog-filestore-data}/{dev,prd}/	Per-env stateful PV/PVCs; wrong reclaim policy can drop CI build caches or JFrog binary data. Platform-team review.
Add a new cluster directory under helm-overrides/	Creates a new deployment target. Pair with the cluster's ApplicationSet change in the sister repo. Per-cluster nodeSelector / tolerations / computeClass MUST be written from scratch, not copied from another cluster (SANCTITY_RULES R5).
Change fullnameOverride in any custom-values.yaml	Service DNS, PVC binding, ConfigMap/Secret references, and downstream Argo Application names depend on it being stable. Almost always wrong to touch.
Bulk find-replace across cluster directories ("normalise" labels, image tags, etc.)	The whole point of per-cluster overrides is divergence. Cross-cluster cleanup is its own PR with its own scope (SANCTITY_RULES R6).
Pin an image tag to a registry outside asia-southeast1-docker.pkg.dev/meesho-devops-admin-0622/admin/sre/	Production overrides go through Meesho's Artifact Registry mirror. Direct Docker Hub / Quay pulls are a supply-chain and rate-limit risk.

Layer 2 — Agent-Readable (advisory only)

Some operations a user might ask for touch systems an agent can analyse but not change.

Operation	Why advisory
"Sync <release> now in Argo CD"	The Sync click is intentional human action. Recommend the command (argocd app sync <name>) or the Argo CD UI path; do not execute.
"Restart pods for <release>"	kubectl operation against a workload cluster. Recommend kubectl rollout restart deploy/<name> -n <ns>; do not execute.
"Why is this pod pending?"	Live cluster state. Recommend kubectl describe pod and walk pod-pending-scheduling.md; do not infer.
"Why did the chart not render?"	Reproduce locally with helm template; recommend the fix. Do not push without PR.
"Add an alert rule for <service>"	Alert rules are in victoria-metrics-alert* chart values here, but routing/notifier config is elsewhere (Pulse / Slack webhook secrets). Recommend the right file; pair with the routing change.
"What's broken on the GKE cluster itself?"	Cluster-level GCP / GKE issues are out of scope for this repo. Recommend the Terraform repo or the platform team.
"Reconcile the Terraform drift for the cluster"	Out of scope — that's terraform-gcp-infra. Refuse + redirect.

Layer 3 — Agent-Blocked (refuse + explain)

Operation	Why blocked	What would unblock
Hand-edit repository.yaml	Owned by registry-bootstrap automation; manual edits are overwritten on the next bootstrap run.	Update the upstream registry that feeds registry-bootstrap.
Bypass pre-commit hooks (--no-verify, git commit -n, removing the hook)	TruffleHog is the last-line secret scan. (SANCTITY_RULES R4)	If a hit is a known false positive, confirm with the platform/security team in writing first.
Push directly to main	Branch protection. (SANCTITY_RULES R1)	(Never legitimate.)
Force-push to main	Same.	(Never legitimate.)
Run helm install, helm upgrade, or kubectl apply against any workload cluster	This is GitOps; in-cluster mutation creates drift Argo CD will reconcile away.	Use the Argo CD UI Sync flow, or the cluster's incident-response toolset.
Curl / probe / interact with int.meesho.int, prd.meesho.int, int.mrouter.int, prd.mrouter.int, or any workload-traffic *.meeshogcp.in host	Production traffic surfaces. (SANCTITY_RULES R3)	(Pre-commit hook telemetry to observe.meeshogcp.in is automated; that is hook infrastructure, not agent action.)
Edit Argo Application / ApplicationSet manifests	They live in github.com/Meesho/devops-infra-argo-config.	Open a PR there.
Modify a chart whose helm-templates/<chart>/ is vanilla upstream, without a documented fork rationale	An accidental fork is silently clobbered on the next sync.	Follow fork-upstream-chart and document the fork in the chart's README.md.
Copy a custom-values.yaml from one cluster to another verbatim	Per-cluster nodeSelector / tolerations / computeClass differ. (SANCTITY_RULES R5)	Author the override from scratch using the per-cluster matrix in contour-nodeselector-tolerations-summary.md and sibling files.

---

Cross-cuts: things to verify on every Layer 1 PR

Pre-commit hooks here are minimal — TruffleHog covers secrets; CAC and Yaak are no-ops because their gating paths don't exist in this repo. The agent is the next line of defence. On every PR, mentally run this checklist:

1. Surgical scope. The PR touches only the cluster × app the task asked for. No drive-by edits to neighbours.
2. Per-cluster scheduling rewritten, not copied. If the change involves nodeSelector / tolerations / computeClass, every cluster has its own topology. Copy-and-rename is the most common silent bug. (contour-nodeselector-tolerations-summary.md)
3. fullnameOverride unchanged. Unless the explicit headline of the PR is a release-name migration.
4. Image tags pin to Meesho's GAR mirror (asia-southeast1-docker.pkg.dev/meesho-devops-admin-0622/admin/sre/<image>), not Docker Hub.
5. Versioned siblings preserved. A delete or rename of a <chart>-green / -latest / -vX.Y.Z directory only proceeds after grepping github.com/Meesho/devops-infra-argo-config for references.
6. Chart.yaml + Chart.lock move together. A dependencies[].version bump without a refreshed lockfile is incomplete.
7. Sister repo paired (where required). A new app under a cluster needs a matching Application in the sister repo. A new cluster directory needs a matching ApplicationSet (or per-cluster Application set) in the sister repo. Note the pairing in the PR description.
8. No * or latest image tags introduced. Argo CD's manual-sync default does not rescue you from a pulled-out-from-under-you image.
9. manifests/ left alone unless the PR's headline says so. storageclass/ and priorityclass/<cluster>/ are cluster-wide singletons.
10. TruffleHog passed. Never bypass.

---

Approval requirements summary

Change category	Reviewer required	CMR required?
Single-cluster custom-values.yaml edit (no scheduling, no fullnameOverride)	App owner	Per BU policy
Add a new app override under an existing cluster	App owner + cluster owner	Yes
Add a new cluster directory	Platform team	Yes
Chart.yaml dependencies[].version bump	Platform team	Yes for prod-fleet charts (Argo CD, Contour, VictoriaMetrics, ingress)
Intentional fork of helm-templates/<chart>/templates/	Platform team — multi-reviewer	Yes
Delete a versioned chart sibling	Platform team — confirm zero sister-repo references	Yes
Edit manifests/storageclass/ or priorityclass/<cluster>/	Platform team	Yes
Pre/post-commit hook script change	Platform team + security (if hook scope changes)	Per CMR matrix
fullnameOverride change	Platform team — multi-reviewer	Yes — emergency-only

CMR = Change Management Request. Per Meesho process; not enforced in-repo, applied at org level.

---

Escalation

If a request falls outside this matrix or you can't classify it cleanly:

1. Refuse the write.
2. Cite this document + the row that matches (or explain why no row matches).
3. Suggest the human asks the platform team or files a CMR.
4. Do not improvise around the boundary.