# System Architecture & Invariants: Kubernetes & Helm Manifest Validation Specialist

## 1. System Overview
Cloud-native Kubernetes and Helm rules. Enforces container resource limits, non-root security contexts, readiness probes, and valid YAML indentation.
All AI agents operating within this repository must adhere strictly to these architectural boundaries.

### Technology Stack
- **Framework**: Kubernetes 1.30+ / Helm 3
- **Language Standard**: YAML / Go Templates
- **UI & Styling**: None / Infrastructure
- **Data Persistence**: etcd / Cloud Native
- **Engineering Philosophy**: architect

## 2. Core Architectural Invariants
- **Self-Documenting Naming**: Expressive function and variable names over verbose redundant comments.
- **Clean Layered Architecture**: Decouple presentation, business logic, and data access layers via interfaces.
- **Schema-Driven Boundaries**: Validate all external data (API, forms, env) with Zod or Pydantic schemas; on failure, reject with a typed error and never pass unvalidated data onward.

## 3. Data Flow & State Management Principles
1. **Unidirectional Data Flow**: State flows top-down; mutations flow through explicit, typed handlers.
2. **Boundary Validation**: External inputs (API payloads, query parameters, environment variables) must be parsed with strict schemas before reaching domain logic.
3. **Surgical Precision**: Diffs must remain minimal and scoped exclusively to the objective. Do not reformat unrelated code.

## 4. Forbidden Anti-Patterns & Operational Guardrails
- **Inspect Before Acting**: Always read and understand existing code and imports before suggesting changes.
- **Minimal Surgical Diffs**: Touch only lines relevant to prompt. Preserve existing comments and formatting.
- **Propose Verification Steps**: With every modification, specify concrete commands or tests to verify correctness.
- **Dependency Caution**: Never introduce new third-party libraries or packages without explicit approval.

## 5. Domain-Specific Invariants
- Never deploy containers using mutable :latest image tags.
- Always include standard app.kubernetes.io/* metadata labels.

## 6. Implementation Reference Patterns

### Preferred Pattern
```go
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-service
  labels:
    app.kubernetes.io/name: api-service
spec:
  replicas: 3
  template:
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 10001
      containers:
        - name: api
          image: registry.example.com/api:v1.4.0
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
          resources:
            requests: { cpu: 100m, memory: 128Mi }
            limits: { cpu: 500m, memory: 512Mi }
          readinessProbe:
            httpGet: { path: /healthz, port: 8080 }
```

### Forbidden Anti-Pattern
```go
apiVersion: apps/v1
kind: Deployment
metadata:
  name: bad-service
spec:
  template:
    spec:
      containers:
        - name: app
          image: myapp:latest # No resource limits, root container, missing probes!
```

## 7. Verification Protocol
Before finalizing any implementation:
1. Always specify explicit resources.requests and resources.limits on every container.
2. Enforce strict securityContext: runAsNonRoot: true, allowPrivilegeEscalation: false, readOnlyRootFilesystem: true.
3. Configure both livenessProbe and readinessProbe with realistic timeouts and initialDelaySeconds.
4. Format Helm template interpolations using nindent filters to preserve valid YAML indentation.