Close S5 app readiness workplan

docs/manifest-server-dry-run.md

@@ -0,0 +1,94 @@
+# Manifest Server Dry-Run Prerequisites
+
+`make k8s-server-dry-run` checks committed manifests and rendered app charts
+against a Kubernetes API server using server-side dry-run. It catches schema and
+admission drift that Helm rendering alone cannot see.
+
+## What The Command Does
+
+The helper in `tools/k8s-server-dry-run.sh`:
+
+1. verifies `kubectl` and `helm` are installed;
+2. verifies a Kubernetes API server is reachable;
+3. optionally creates the target namespace when
+   `DRY_RUN_CREATE_NAMESPACES=true`;
+4. renders `charts/vergabe-teilnahme/` with
+   `helm/vergabe-teilnahme-values.yaml`;
+5. runs `kubectl apply --dry-run=server -f manifests`;
+6. runs `kubectl apply --dry-run=server` against the rendered chart output.
+
+The namespace creation step is a real apply, not a dry-run. Use
+`DRY_RUN_CREATE_NAMESPACES=true` only against a disposable or approved
+representative cluster where creating the app namespace is acceptable.
+
+## Representative Cluster Requirement
+
+The check expects a live Kubernetes API server whose version, admission
+webhooks, and installed APIs are close enough to Railiance to be meaningful. A
+pure local render or unseeded kind cluster is not enough.
+
+The current `vergabe-teilnahme` release uses built-in Kubernetes APIs:
+
+- `apps/v1` Deployment;
+- `v1` Service;
+- `v1` PersistentVolumeClaim when media persistence is enabled;
+- `networking.k8s.io/v1` Ingress.
+
+For realistic S5 validation, the representative cluster should also have the
+same ingress class, cert-manager issuer posture, NetworkPolicy posture, and
+admission policies as Railiance. Future app manifests that introduce CNPG,
+cert-manager, Traefik, External Secrets, or other CRDs require those CRDs and
+webhooks to be installed before the dry-run result is meaningful.
+
+## Runner And Credential Requirements
+
+Local operator runs require:
+
+- `kubectl` context pointed at the representative cluster;
+- credentials with `get` access for API discovery;
+- server-side dry-run permission for the rendered resources;
+- namespace create/apply permission only when
+  `DRY_RUN_CREATE_NAMESPACES=true`.
+
+CI runs require forge-owned runner prerequisites:
+
+- a runner label approved for S5 release checks, such as `s5-release-check` or
+  `cluster-dry-run`;
+- approved kubeconfig or equivalent cluster access delivery;
+- runner placement that is allowed to reach the representative API server;
+- no kubeconfig, bearer token, package token, or secret value stored in Git.
+
+The runner label contract and secret boundary live in
+`/home/worsch/railiance-forge/docs/ci-runner-actions-gitops-ownership.md`.
+
+## Failure Classification
+
+Treat these as release-blocking when the representative cluster and runner are
+known-good:
+
+- Helm render fails;
+- server-side dry-run rejects a changed manifest;
+- Kubernetes schema or admission policy rejects an app resource;
+- the rendered image reference or required Secret name is structurally invalid.
+
+Treat these as prerequisite gaps rather than app release failures:
+
+- no runner with the required label is available;
+- the runner cannot reach the representative cluster;
+- kubeconfig or secret delivery is missing;
+- required CRDs/admission webhooks are absent from the representative cluster;
+- namespace creation is forbidden while `DRY_RUN_CREATE_NAMESPACES=true`.
+
+For prerequisite gaps, link or create the owning forge, cluster, platform, or
+enablement workplan instead of weakening the S5 app chart.
+
+## Enforcement Gate
+
+The workflow in `.gitea/workflows/manifest-server-dry-run.yaml` is ready to
+enforce PR checks only when:
+
+- forge has published the runner label and placement evidence;
+- cluster/platform have provided representative API access and secret delivery;
+- the namespace side effect is accepted or pre-provisioned;
+- at least one successful dry-run result is recorded for the current release
+  surface.