devops-infra-argo-config-gcp/docs/global/AGENT_BOUNDARIES.md

Agent Boundaries — devops-infra-argo-config

Authoritative document defining which operations agents can perform in this repository.

Audience: Claude Code agents, human reviewers of agent-generated PRs.

Model: 3-Layer Operating Model per AI Blitz Plan §4.2.

---

The 3-Layer Model

Layer	What agents do	Safety gate
Layer 1-T (Tool-Mediated)	Generate YAML diff via tools, open PR. No direct YAML edits.	PR review by platform team.
Layer 2 (Agent-Readable Advisory)	Research, analyze, suggest. Human executes.	Human judgment.
Layer 3 (Agent-Blocked)	Refuse the write. Direct user to correct owner.	Hard stop.

This repo is Layer 1-T. All YAML changes should go through incubator-tool or argo-app-tool where available. Direct YAML edits bypass tool validation but are acceptable when tools are not available, provided the PR checklist is followed.

---

Per-operation classification

Layer 1-T — Standard operations

Operation	Files affected	Blast radius	Tool	Approval
Add appSpec entry to values file	values/<env>/<cluster>-values.yaml	Single cluster, single tool	argo-app-tool	Platform team PR review
Remove appSpec entry from values file	values/<env>/<cluster>-values.yaml	Single cluster, single tool	argo-app-tool	Platform team PR review
Update appSpec entry (chartDir, valuesDir, namespace)	values/<env>/<cluster>-values.yaml	Single cluster, single tool	argo-app-tool	Platform team PR review
Add nameOverride to appSpec entry	values/<env>/<cluster>-values.yaml	Single cluster, single tool	argo-app-tool	Requires justification in PR
Create incubator file for new cluster	incubator/<env>/<cluster>.yaml	New cluster bootstrap	incubator-tool	Platform team PR review
Create values file for new cluster	values/<env>/<cluster>-values.yaml	New cluster bootstrap	argo-app-tool	Platform team PR review
Add external-name-service files	external-name-service-*/**	Cross-cluster DNS routing	Manual	Platform team PR review
Modify AppProject	projects/*.yaml	All Applications referencing the project	Manual	Platform team + security review

Layer 1-T — HIGH RISK operations

These are Layer 1-T (agent may generate the diff + open PR) but carry elevated risk:

Operation	Why high risk	Extra requirement
Edit generic-argo-apps-chart/	Auto-sync means a bad template change breaks ALL clusters immediately	Explicit platform-team sign-off; test with helm template against multiple values files
Modify clusterSpec.destination in values file	Redirects all tools to a different cluster	Verify cluster name exists in GKE
Change teamSpec.source.targetRevision	Switches chart source branch — affects all tools on the cluster	Must match env branch: main (prd), develop (stg/dev), pre-prod (int)
Change teamSpec.source.repoURL	Switches chart source repo entirely	Requires platform-team approval
Bulk-add appSpec entries to multiple clusters	Fleet-wide tool rollout	Each cluster's entry must be individually verified

Layer 2 — Advisory only (no agent write)

Operation	Agent action
Run argocd app sync <appName>	Suggest the command; do not execute. Infra apps auto-sync from main.
Run argocd app diff <appName>	Suggest the command if cluster access is available.
Investigate sync failure	Read logs, analyze values, suggest fix. See runbooks/argocd-sync-failure.md.
Check which clusters have a tool	Run grep -rl 'name: <tool>' values/ — read-only.
Audit AppProject scope	Read projects/ and list dependent Applications — advisory only.

Layer 3 — Hard stops (agent must refuse)

Operation	Why blocked	Redirect
Edit repository.yaml	Owned by registry-bootstrap automation	Direct user to upstream automation
Run kubectl apply against a cluster	Out of scope — this repo is GitOps, not in-cluster mutation	Direct to incident response procedures
Push directly to main	Branch protection enforced at org level	Open PR instead
Delete an incubator file	Orphans the cluster's tooling	Require confirmation that cluster is decommissioned
Force-push to any branch	Destructive, irreversible	Never do this
Skip pre-commit hooks (--no-verify)	Bypasses TruffleHog, CAC, Yaak	Fix the hook failure instead
Add secrets to YAML	TruffleHog will block; if bypassed, requires history purge	Use external-secrets operator

---

Cross-cut verification checklist (every Layer 1-T PR)

Before merging any agent-generated PR:

1. Tool was used (or manual edit follows tool conventions).
2. chartDir exists in devops-infra-helm-charts/helm-templates/.
3. valuesDir exists in devops-infra-helm-charts/helm-overrides/<cluster>/.
4. Auto-generated Application name is <= 253 characters.
5. No name collision with existing appSpec entries in the same values file.
6. nameOverride is used only when justified (R7).
7. spec.project references an existing AppProject (sre or sec).

---

Escalation procedure

When an operation falls outside Layer 1-T boundaries:

1. Refuse the write.
2. Cite this document and the specific layer/operation.
3. Suggest the human ask the platform team or file a CMR (Change Management Request).