added repo

docs/global/AGENT_BOUNDARIES.md

@@ -0,0 +1,94 @@
+# 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).