# 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](../platform/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).