Documented no-KSail validation fallback validates zero base manifests

[devantler]

🤖 Generated by the Agentic Engineer

Evidence

AGENTS.md prescribes a no-KSail fallback for manifest validation, in both the Validation section
and the agent-facing Maintenance section:

Without KSail, both overlays MUST build: kubectl kustomize k8s/clusters/local/ and
kubectl kustomize k8s/clusters/prod/

That command does not validate manifests. Measured on main today:

$ kubectl kustomize k8s/clusters/local/ | yq -r '[.kind, .metadata.name] | join("  ")'
Kustomization  apps
Kustomization  bootstrap
Kustomization  infrastructure
Kustomization  infrastructure-controllers

$ kubectl kustomize k8s/clusters/local/ | grep -c 'auth-proxy\|oauth2-proxy\|cluster-policies'
0

It emits 4 documents — the Flux Kustomization wiring only — and zero base manifests. For
comparison, ksail workload validate on the same tree validates 465 files under bases/.

This is by design: k8s/clusters/ overlays only wire the four Flux Kustomizations, and the actual
manifests are delivered as an OCI artifact and reconciled by Flux. The build succeeding says nothing
about the files a change actually touched.

Impact

The failure is silent and points the wrong way. An agent or contributor without KSail installed edits
something under k8s/bases/**, runs the documented fallback, sees both overlays build, and concludes
the change is validated — when none of it was parsed. A malformed base manifest reaches CI (or a
reviewer) carrying an explicit local "validated" claim.

I hit this today on #2723: after editing k8s/bases/infrastructure/controllers/auth-proxy/config-map.yaml,
both overlays built cleanly and a grep for my own change in the rendered output returned 0. Only
running ksail workload validate and then grepping its log for the changed path proved the file was
actually covered.

Expected behaviour

The documented fallback should either validate the manifests it implies, or say plainly that it does
not and name what it does cover.

Acceptance criteria

• AGENTS.md no longer presents kubectl kustomize k8s/clusters/{local,prod} as validation of
  changed manifests; it states that this builds only the Flux Kustomization wiring.
• A no-KSail path that genuinely parses changed base manifests is documented (e.g. building the
  provider overlay that actually includes them, and/or kubectl apply --dry-run=client -f <file>
  per changed file, which the doc already mentions separately).
• The guidance tells the reader to confirm coverage — grep the validator's output for the
  changed path — rather than trusting a zero-exit.
• Both the Validation and Maintenance sections are corrected (the claim appears in both).

Rough size: small — a documentation fix plus verifying the replacement command actually covers a
changed base file.

[coderabbitai]

⚠️ Possible Duplicate Issue(s)

• The documented no-KSail validation fallback builds no manifests, so it cannot fail on a manifest defect #3088

🔗 Related PRs

#2704 - fix(aws): constrain eks-ci KMS grant creation [merged]
#2738 - ci: verify ksail release downloads [merged]
#3037 - fix(cilium): refuse a zero-count gate release and correct the runbook order [merged]
#3103 - feat(security): assert the node image verifier can enforce at all [merged]
#3109 - fix(deploy): avoid redundant GHCR node reboots [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!