feat: bring paperclip-operator to parity (tier 1/2 feature port)

[stubbi]

Summary

Brings the paperclip-operator up to parity with its sibling operators (openclaw-operator, hermes-operator) by porting a tier-1/2 feature set. Each feature is a separate commit. The repo already had digest-pinning (#64) and CEL no-:latest validation, so those are not re-added.

Ported features

1. Weekly verify-signing workflow (template: hermes-operator .github/workflows/verify-signing.yaml). New make verify-signing cosign-verifies the latest published ghcr.io/paperclipinc/paperclip-operator image and its SBOM attestation, with the identity regexp and OIDC issuer adapted to this repo's release.yaml. The scheduled workflow opens an infra-broken issue on failure.

2. Resource-builder benchmarks (template: openclaw-operator resources_bench_test.go + make bench). The make bench target already existed; added internal/resources/resources_bench_test.go with benchmarks for BuildStatefulSet (server/database/redis), BuildService, BuildNetworkPolicy, BuildIngress, BuildPodDisruptionBudget, BuildHorizontalPodAutoscaler, BuildPersistentVolumeClaim and BuildServiceAccount across minimal and fully-loaded specs.

3. First-class spec.suspended scale-to-zero (template: openclaw/hermes). StatefulSetReplicas forces 0 replicas when suspended; a Suspended phase and Suspended condition are set; the StatefulSet readiness condition reports drained/suspended; HPA replica preservation yields to scale-to-zero. Unit tests plus an envtest assertion. CRDs regenerated.

4. Zombie-process reaping via shareProcessNamespace (template: openclaw statefulset builder). New spec.shareProcessNamespace *bool (default true) sets pod ShareProcessNamespace so the pause container reaps zombies left by the Node.js server; opt-out by setting false. Unit test.

5. Grafana dashboards + PrometheusRule (template: openclaw observability builders). New spec.observability.metrics.prometheusRule and .grafanaDashboard toggles. BuildPrometheusRule emits default alerts adapted to this operator's metrics (paperclip_reconcile_total, paperclip_instance_ready, paperclip_instance_phase, reconcile duration, crash-loop, OOM, PVC near-full), skipped when the monitoring CRD is absent. BuildGrafanaDashboard{Operator,Instance} emit dashboard ConfigMaps. Builders + unit tests, controller wiring via CreateOrUpdate, prometheusrules RBAC marker synced into config/rbac and the Helm chart, CRDs regenerated.

6. mkdocs-material docs site + auto API reference (template: openclaw-operator docs-site/ + crd-ref-docs). docs/api-reference.md is generated from api/v1alpha1 via crd-ref-docs (make api-docs); added docs-site/ (mkdocs.yml, crd-ref-docs.yaml, requirements.txt, README), docs/index.md, the crd-ref-docs/api-docs/docs-venv/docs-serve/docs-build Makefile targets, and a Docs Build CI job that fails if the API reference drifts and runs a strict mkdocs build.

7. Conformance test suite (template: hermes-operator test/conformance/ + conformance.yaml CI). Adapted to the Instance CR, gated on KUBECONFIG so it skips on unit/envtest jobs. Categories: negative (schema/CEL deny), idempotency (10-reconcile fingerprint canary), gitops-coexistence (repeated server-side apply no-flap), upgrade (in-place tag bump with PVC identity preserved), failure-modes (operator pod kill + recovery). make conformance-* targets and a Conformance CI workflow (negative + idempotency on kind).

8. Enriched status conditions (template: openclaw/hermes condition catalogues). Added NetworkPolicyReady, RBACReady, IngressReady, HTTPRouteReady, PDBReady, HPAReady and BackupReady, set by the controller in their reconcile paths with ObservedGeneration, plus the Suspended condition. Names kept consistent with the sibling operators.

Validation

• go build ./... and go vet ./...: pass.
• make lint (golangci-lint v2.11.4): 0 issues.
• go test ./internal/resources/... ./api/...: pass.
• make test (envtest, k8s 1.33): all packages pass, including the new suspended envtest case and the conformance suite (skips without KUBECONFIG).
• make bench: runs all builder benchmarks.
• bash hack/check-helm-rbac-sync.sh: in sync.
• bash hack/sync-chart-crds.sh --check: in sync.
• helm lint charts/paperclip-operator: 0 failures.
• make docs-build: strict mkdocs build succeeds; make api-docs regenerates docs/api-reference.md.
• Dash scan (grep -rnP '[\x{2013}\x{2014}]') over every changed file: clean.

Notes

• The OLM bundle/manifests CRD is pre-existing-stale (it already lacked fields like cloudSandbox before this branch) and make bundle requires interactive input because config/manifests/bases has no base CSV in this repo. The OLM CSV was not touched by this PR, so make bundle-validate was not required; the bundle is refreshed by release tooling. Left untouched to avoid hand-editing a generated artifact incorrectly.
• The conformance and docs CI jobs require a kind cluster / Python respectively and were validated locally where possible (conformance compiles + skips, docs build strict).

Do not merge / do not enable auto-merge.

🤖 Generated with Claude Code