fix(kickstart): prefer az acr build and safeguards validation in cloudshell

agents/kickstart-reviewer.agent.md

@@ -19,11 +19,13 @@ You review deployment artifacts generated by the Kickstart agent. Your job is to
 ## Review Process
 
 1. Invoke `/kickstart-review` for the full per-artifact checklist (Dockerfile, Kubernetes manifests, Bicep, GitHub Actions) plus dry-run validation (`kubectl apply --dry-run=client`, `az bicep build`).
-2. Invoke `/kickstart-safeguard-checklist` to validate manifests against AKS deployment safeguard rules.
+2. Invoke `/kickstart-safeguard-checklist` to validate manifests against AKS deployment safeguard rules. Report **Part A** (policy-enforced AKS Deployment Safeguards) separately from **Part B** (pod security / best practice), and treat a FAIL on a *mutating* safeguard (A2 requests, A3 spread/anti-affinity, A6 reserved taints) as a real defect — the cluster will rewrite the object rather than reject it, so it must be fixed in the YAML.
 3. Invoke `/kickstart-security-hardening` for security-specific checks (RBAC scope, Key Vault, encryption, network isolation).
 
 Work through every generated artifact against those checklists — do not re-derive the criteria here.
 
 ## Output
 
 Present findings as a checklist with **PASS** ✓, **FAIL** ✗, or **WARN** ⚠ for each item. If any FAIL items exist, list specific fixes needed.
+
+Images are always built with `az acr build`, never `docker build` — never ask for local Docker output or tell the user to install Docker. Verify the entry point via the Dockerfile's build-time `RUN test -f <entrypoint>` assertion.

agents/kickstart.agent.md

@@ -66,7 +66,7 @@ Handle each starting point (ask via `vscode_askQuestions` only when it wasn't al
     }]
   }
   ```
-  Clone with `run_in_terminal`, then load `/kickstart-samples` for the pre-filled profile and confirm it with the user. **Skip Phase 1's questions** — go straight to **Phase 2 (Configure Infrastructure)**. Do NOT ask the user for app name, port, language, or any discovery questions — but still run the quick structure scan from `/kickstart-samples` to confirm each service's build context, Dockerfile path, and entry point before generating anything.
+  Clone with `run_in_terminal`, then load `/kickstart-samples` for the pre-filled profile and confirm it with the user. **Skip Phase 1's questions** — go straight to **Phase 2 (Configure Infrastructure)**. Do NOT ask the user for app name, port, language, or any discovery questions — but still run the quick structure scan from `/kickstart-samples` to confirm each service's build context, Dockerfile path, and entry point, before generating anything.
 - **Use my current workspace**: Proceed to **Phase 1 (Discover)**.
 
 ## Phases
@@ -85,15 +85,15 @@ Follow `/kickstart-configure-infra`. Do NOT pick subscriptions or run `az aks cr
 Follow `/kickstart-design`. Present architecture summary (container strategy, AKS Automatic, Gateway API, Workload Identity, ACR, monitoring). Get user approval via `vscode_askQuestions`. Run `/kickstart-cluster-status` before transitioning.
 
 ### 4 — Generate
-Follow `/kickstart-generate`. Produce Dockerfile (reuse an existing one when present), K8s manifests (`k8s/`), Bicep (`infra/`), GitHub Actions workflow — driven by the structure map, with every `COPY`/`ADD` path validated against the build context. Use actual resource names from Phase 2. Pin image tags — never `:latest`. Build and inspect each image (confirm the entry point landed) before exiting. Run `/kickstart-cluster-status` before transitioning.
+Follow `/kickstart-generate`. Produce Dockerfile (reuse an existing one when present), K8s manifests (`k8s/`), Bicep (`infra/`), GitHub Actions workflow — driven by the structure map, with every `COPY`/`ADD` path validated against the build context. Use actual resource names from Phase 2. Pin image tags — never `:latest`. Emit manifests that already satisfy the mutating AKS Deployment Safeguards (CPU/memory **requests**, `topologySpreadConstraints` or pod anti-affinity, unique per-service Service selectors, probes, CSI `storageClassName`, no `kubernetes.azure.com/*` labels or `CriticalAddonsOnly` toleration). Build each image with `az acr build` (server-side; never `docker build`) and assert the entry point with a `RUN test -f` line in the Dockerfile before exiting. Run `/kickstart-cluster-status` before transitioning.
 
 ### 5 — Review
-Follow `/kickstart-review`. Show the Dockerfile source→destination map for confirmation and verify the image builds with the entry point present, then run `/kickstart-safeguard-checklist` validation. Present pass/fail/warn checklist. Fix failures before proceeding. Run `/kickstart-cluster-status` before transitioning.
+Follow `/kickstart-review`. Show the Dockerfile source→destination map for confirmation and verify the image builds with the entry point present via `az acr build` plus its build-time entry-point assertion — then run `/kickstart-safeguard-checklist` validation. Present pass/fail/warn checklist. Fix failures before proceeding. Run `/kickstart-cluster-status` before transitioning.
 
 ### 6 — Pre-Deploy Check
 Follow `/kickstart-handoff` — it carries the full strict-order playbook: cluster readiness (6a), metadata detection (6b), ACR attachment verification (6c — idempotent; the registry is usually already attached during cluster setup), kubelogin (6d), and the consolidated permission probes (6e–6g) via the bundled `aks.checkDeploymentPermissions` command. Escalate through `/kickstart-pim-activation` whenever a role assignment returns 403. Confirm readiness with the user via `vscode_askQuestions` before deploying.
 
 ### 7 — Deploy
-Follow `/kickstart-deploy` — build & push to ACR (using each service's build context and Dockerfile path from the structure map, never `.`), get credentials, apply manifests, then verify and health-check the running app (hit its endpoint, compare expected vs actual — not just pod readiness), executed step by step via `run_in_terminal` with confirmation between each and error classification on failure.
+Follow `/kickstart-deploy` — build & push to ACR with `az acr build` (server-side, never `docker build`; using each service's build context and Dockerfile path from the structure map, never `.`), get credentials, apply manifests, then verify and health-check the running app (hit its endpoint, compare expected vs actual — not just pod readiness), executed step by step via `run_in_terminal` with confirmation between each and error classification on failure.
 
 Once the app is running, offer to commit the generated artifacts (Dockerfile, `k8s/`, `infra/`, workflow). If the user wants to commit or open a PR, follow `/kickstart-github-pr-conventions` for branch naming, Conventional Commits, and PR structure.

skills/kickstart-deploy/SKILL.md

@@ -11,12 +11,16 @@ Deploy using Azure CLI and `kubectl`. Execute each step via `run_in_terminal`, c
 ## Steps
 
 1. **Build and push**: `az acr build --registry <acr> --image <image>:<tag> -f <dockerfilePath> <buildContext>`
+   `az acr build` runs **server-side on the ACR remote task builders** — always use it, never `docker build` + `docker push`. Kickstart runs in Azure Cloud Shell, which has no Docker daemon, and a single remote build keeps the pushed digest and the deployed image identical.
    Use the build context and Dockerfile path from the structure map — never assume repo root (`.`). For monorepos, build each service from its own context. Tag with a version (e.g. v1.0.0), never `:latest`.
+   Requires `AcrPush` or `Container Registry Tasks Contributor` (verified in Pre-Deploy Check). Keep the command in the foreground so its streamed log holds an idle Cloud Shell session open, and make sure `.dockerignore` excludes bulk (the whole context is uploaded on each build).
+   Third-party images the app depends on (Redis, Postgres, RabbitMQ) can't be `az acr build`-ed — bring them in with `az acr import --name <acr> --source docker.io/library/<img>:<tag> --image <img>:<tag>`.
 
 2. **Get credentials**: `az aks get-credentials --resource-group <rg> --name <cluster> --overwrite-existing`
    kubelogin handles AAD auth automatically (verified in Pre-Deploy Check). Never use `--admin`.
 
-3. **Apply manifests**: `kubectl apply -f k8s/`
+3. **Apply manifests**: preview with `kubectl apply --dry-run=server -f k8s/`, then `kubectl apply -f k8s/`.
+   Expect mutation: AKS Automatic's Deployment Safeguards rewrite on admission — missing CPU/memory requests get defaults, missing spread rules get anti-affinity/topology constraints, a stray `CriticalAddonsOnly` toleration is stripped. If Phase 4 generated compliant manifests these are no-ops; if `kubectl get -o yaml` differs from your file, that's the mutator, not a bug.
 
 4. **Verify**: `kubectl get pods -n <namespace>` and `kubectl get services -n <namespace>`
    If pods not Ready, run `kubectl describe pod <name>` and `kubectl logs <name>` to diagnose.
@@ -33,6 +37,7 @@ Classify failures:
 - **config** — missing or invalid configuration (subscription, RG, cluster, ACR, manifest)
 - **dependency** — missing CLI tool, extension, or container image
 - **cluster** — pod CrashLoopBackOff, ImagePullBackOff, scheduling, quota
+- **safeguard** — admission rejected by a Deployment Safeguard (e.g. `:latest` tag, non-CSI StorageClass, duplicate Service selector, AKS-reserved label, node edit). Fix the manifest to satisfy the rule; never disable the policy.
 
 Provide specific `az` or `kubectl` fix commands. Offer retry via `vscode_askQuestions`.
 

skills/kickstart-discover/SKILL.md

@@ -26,6 +26,16 @@ Never assume a flat repo. Apps often live in nested or monorepo layouts (`src/<s
 
 Use `codebase`/`search` to confirm each path actually exists — do not infer it from the language alone. Surface this map to the user and let them correct it before proceeding.
 
+## Build environment
+
+All container images are built with **`az acr build`** — server-side on the ACR remote task builders. Never `docker build`. Kickstart runs in Azure Cloud Shell, which has no Docker daemon, and a single remote build path keeps behavior identical everywhere.
+
+Cloud Shell constraints to honor:
+
+- Clone into `~/clouddrive/` (persistent, ~5 GB) rather than the ephemeral home dir.
+- `az acr build` needs the Phase 2 ACR to exist and the caller to hold `AcrPush` (or `Container Registry Tasks Contributor`) — see `/kickstart-handoff`.
+- Keep `az acr build` in the foreground so its streamed log holds an idle session open, and keep `.dockerignore` tight (the whole build context uploads on every build).
+
 ## What to collect
 
 - App name
@@ -43,4 +53,4 @@ Use `codebase`/`search` to confirm each path actually exists — do not infer it
 - When the answer is open-ended (app name), use `allowFreeformInput: true`.
 
 ## Exit Criteria
-You know the app name, language, framework, port, key deps, env vars, CI status, and a confirmed per-service structure map (build context + entry point + existing Dockerfile path) for every deployable service. Announce: "Discovery complete — moving to Configure Infrastructure."
+You know the app name, language, framework, port, key deps, env vars, CI status, a confirmed per-service structure map (build context + entry point + existing Dockerfile path) for every deployable service. Announce: "Discovery complete — moving to Configure Infrastructure."

skills/kickstart-generate/SKILL.md

@@ -27,7 +27,35 @@ Load these for detailed patterns as you author each artifact:
 
 **Dockerfile**: Multi-stage build, pinned base image (never `:latest`), non-root user, `.dockerignore`. `COPY`/`ADD` paths validated against the build context; `CMD` runs the real entry point.
 
-**K8s Manifests** (`k8s/`): `namespace.yaml`, `deployment.yaml` (resource limits, probes, `runAsNonRoot`, Workload Identity labels, env from ConfigMap/Secret), `service.yaml` (ClusterIP), `httproute.yaml` (Gateway API, not Ingress). See `/kickstart-workload-identity`.
+**K8s Manifests** (`k8s/`): `namespace.yaml`, `deployment.yaml` (resource requests **and** limits, probes, `runAsNonRoot`, Workload Identity labels, env from ConfigMap/Secret), `service.yaml` (ClusterIP), `httproute.yaml` (Gateway API, not Ingress). See `/kickstart-workload-identity`.
+
+### Generate safeguard-compliant manifests up front
+
+AKS Automatic enforces **Deployment Safeguards**, and several of them *mutate* your manifest on apply. If you don't emit these yourself, the cluster silently rewrites the object and the Phase 7 `kubectl get`/`diff` output won't match what you generated. Emit all of the following by default — see `/kickstart-safeguard-checklist` for the authoritative rule list and mutation outcomes.
+
+- **CPU + memory `requests` on every container** (mutating if omitted), alongside limits:
+  ```yaml
+  resources:
+    requests: { cpu: 100m, memory: 128Mi }
+    limits:   { cpu: 500m, memory: 512Mi }
+  ```
+- **`topologySpreadConstraints` or pod anti-affinity** (mutating if omitted). Prefer topology spread:
+  ```yaml
+  topologySpreadConstraints:
+    - maxSkew: 1
+      topologyKey: kubernetes.io/hostname
+      whenUnsatisfiable: ScheduleAnyway
+      labelSelector:
+        matchLabels: { app: <service> }
+  ```
+- **Readiness *and* liveness probes** on every container — use the real health path and port from the structure map, never a guessed `/healthz`.
+- **Unique Service selectors** — each Service must select exactly one workload. In a monorepo do **not** reuse `app: <appName>` across services; use `app: <serviceName>` (or `app.kubernetes.io/name` + `app.kubernetes.io/component`) so no two Services overlap.
+- **No AKS-specific labels** — never set `kubernetes.azure.com/*` labels on your own objects. (`azure.workload.identity/*` labels and annotations are fine and required.)
+- **No reserved system-pool taints/tolerations** — do not add a `CriticalAddonsOnly` toleration to app pods; it would place them on the system pool and AKS strips it anyway.
+- **CSI StorageClass for any PVC** — set `storageClassName` explicitly to a CSI class (`managed-csi`, `managed-csi-premium`, `azurefile-csi`); never rely on an in-tree or unset default.
+- **Pinned image tags** — no `:latest` anywhere, including init containers and sidecars.
+- **Allowed images only** — every image must come from the Phase 2 ACR (`<acr>.azurecr.io/...`) if the cluster restricts registries; flag any third-party image (Redis, Postgres, RabbitMQ) that would need importing via `az acr import`.
+- **Never edit individual nodes** — no node-targeted manifests, `kubectl label node`, `kubectl taint node`, or node-name `nodeSelector`. Use node pools instead.
 
 **Bicep** (`infra/main.bicep`): AKS Automatic + ACR + Managed Identity + federated credential. Parameterized, pinned API versions. ARM resource IDs follow `/subscriptions/{sub}/resourceGroups/{rg}/providers/{ns}/{type}/{name}`. See `/kickstart-bicep-authoring` and `/kickstart-acr-integration`.
 
@@ -37,18 +65,26 @@ Load these for detailed patterns as you author each artifact:
 - Use actual resource names from the Configure phase.
 - Never use `:latest` tags.
 - Honor each service's build context and entry point from the structure map; reuse existing Dockerfiles instead of duplicating them.
-- All K8s manifests must comply with AKS deployment safeguards (restricted pod security, no privileged, no hostPath).
+- All K8s manifests must comply with AKS deployment safeguards (restricted pod security, no privileged, no hostPath) **and** must pre-satisfy the mutating safeguards above so the cluster doesn't rewrite them on apply.
+- Build images with `az acr build` only — never `docker build`.
 - After writing all files, confirm with user via `vscode_askQuestions`.
 
 ## Validate the build (before exit)
 
-Do not hand off unbuilt artifacts. For each Dockerfile, build and inspect before announcing completion:
+Do not hand off unbuilt artifacts. Build every Dockerfile with **`az acr build`** — server-side on the ACR remote task builders. Never `docker build`; there is no Docker daemon in Cloud Shell, and one build path keeps the validated image and the deployed image identical.
 
-1. **Build** from the service's build context:
-   - Local Docker/Podman daemon available: `docker build -t kickstart-validate-<svc>:check -f <dockerfilePath> <buildContext>`.
-   - Otherwise build in ACR (also catches missing `COPY` sources): `az acr build --registry <acr> --image kickstart-validate/<svc>:check -f <dockerfilePath> <buildContext>`.
-2. **Inspect contents** (when built locally): `docker run --rm kickstart-validate-<svc>:check ls -la <workdir>` — confirm the entry point and expected files landed where the app runs from. A build that succeeds but places files in the wrong dir is exactly the failure this step catches.
-3. If the build fails or the entry point is missing, fix the Dockerfile/paths and rebuild — do not proceed to Review with a broken image.
+1. **Build in ACR** from the service's own build context. This also catches missing `COPY`/`ADD` sources:
+   ```bash
+   az acr build --registry <acr> --image kickstart-validate/<svc>:check -f <dockerfilePath> <buildContext>
+   ```
+2. **Assert the entry point at build time.** Add to the Dockerfile's final stage so a wrong path fails the ACR build itself:
+   ```dockerfile
+   RUN test -f <entrypointPath>
+   ```
+   The assertion runs before the cluster exists, so a wrong path is caught immediately.
+3. If the build fails or the assertion trips, fix the Dockerfile/paths and rebuild — do not proceed to Review with a broken image.
+
+Keep `.dockerignore` tight: the entire build context is uploaded to ACR on every build.
 
 ## Exit Criteria
-All artifacts written, every Dockerfile builds, and the entry point is confirmed present in the image. Announce: "Artifacts generated and build-validated — moving to Review."
+All artifacts written, every Dockerfile builds via `az acr build`, and the build-time entry-point assertion passes. Announce: "Artifacts generated and build-validated — moving to Review."