pkg/cvo: Add Lightspeed proposal integration (OCPSTRAT-2618)

Integrate CVO with the Lightspeed agent framework by creating Proposal
CRs when available updates are discovered. This includes OLM operator
lifecycle readiness checks, product lifecycle (PLCC) data via a shared
agentic-skills image, and proposal creation gated behind the
LightspeedProposals feature gate.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: harche

AGENTS.md

@@ -188,4 +188,84 @@ Subsystems include: `pkg/cvo`, `pkg/payload`, `lib/resourceapply`, `hack`, etc.
 
 ### Development and Testing
 - Never test against production clusters - always use disposable test environments
-- CVO has significant control over cluster state and can disrupt operations during development
+- CVO has significant control over cluster state and can disrupt operations during development
+
+## Lightspeed Proposal Integration
+
+The CVO creates `Proposal` CRs (API group `agentic.openshift.io/v1alpha1`) when available updates are discovered, gated behind the `LightspeedProposals` feature gate.
+
+### Key files
+- `pkg/proposal/proposal.go` — Creates Proposal CRs with pre-collected readiness data
+- `pkg/proposal/proposal_test.go` — Unit tests for proposal creation and dedup
+- `pkg/cvo/cvo.go:maybeCreateLightspeedProposal` — Runs readiness checks, calls proposal creator
+- `pkg/cvo/availableupdates.go:188` — Entry point after Cincinnati sync
+- `pkg/featuregates/featuregates.go` — `LightspeedProposals()` feature gate
+- `install/*lightspeed*` — Agent, Workflow, and system prompt manifests (applied by CVO from payload)
+- Skills are consumed from the shared `agentic-skills` image (openshift/agentic-skills repo)
+
+### Deploying dev CVO with Lightspeed proposals
+
+Requires: lightspeed-operator already deployed on the cluster (CRDs, agent, sandbox).
+
+```bash
+# 1. Build binary and payload override (excludes CVO deployment manifest to prevent self-revert)
+cd /path/to/cluster-version-operator
+CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -mod=vendor \
+  -o _output/linux/amd64/cluster-version-operator ./cmd/cluster-version-operator/
+
+# 2. Create payload override directory with release-metadata (so CVO detects correct version)
+mkdir -p _output/payload-override/{manifests,release-manifests}
+cp install/* _output/payload-override/manifests/
+rm _output/payload-override/manifests/*30_deployment*   # prevent self-revert
+CLUSTER_VERSION=$(oc get clusterversion version -o jsonpath='{.status.desired.version}')
+cat > _output/payload-override/release-manifests/release-metadata <<EOF
+{"kind":"cincinnati-metadata-v0","version":"${CLUSTER_VERSION}"}
+EOF
+cat > _output/payload-override/release-manifests/image-references <<EOF
+{"kind":"ImageStream","apiVersion":"image.openshift.io/v1","metadata":{"name":"${CLUSTER_VERSION}"},"spec":{"tags":[]}}
+EOF
+
+# 3. Build and push container image
+cat > Dockerfile.dev <<'EOF'
+FROM registry.access.redhat.com/ubi9-minimal:latest
+COPY _output/linux/amd64/cluster-version-operator /usr/bin/cluster-version-operator
+COPY install /manifests
+COPY _output/payload-override /payload
+ENTRYPOINT ["/usr/bin/cluster-version-operator"]
+EOF
+TAG="v$(date +%s)"
+docker build --platform linux/amd64 -f Dockerfile.dev -t quay.io/harpatil/cvo-lightspeed:${TAG} .
+docker push quay.io/harpatil/cvo-lightspeed:${TAG}
+
+# 4. Deploy: single atomic patch (image + args + env) to avoid partial reverts
+RELEASE_IMAGE=$(oc get clusterversion version -o jsonpath='{.status.desired.image}')
+API_HOST=$(oc get infrastructure cluster -o jsonpath='{.status.apiServerInternalURI}' | sed 's|https://||' | cut -d: -f1)
+oc patch deployment cluster-version-operator -n openshift-cluster-version --type json -p "[
+  {\"op\":\"replace\",\"path\":\"/spec/template/spec/containers/0/image\",\"value\":\"quay.io/harpatil/cvo-lightspeed:${TAG}\"},
+  {\"op\":\"replace\",\"path\":\"/spec/template/spec/containers/0/imagePullPolicy\",\"value\":\"Always\"},
+  {\"op\":\"replace\",\"path\":\"/spec/template/spec/containers/0/args\",\"value\":[
+    \"start\",\"--release-image=${RELEASE_IMAGE}\",\"--enable-auto-update=false\",
+    \"--listen=0.0.0.0:9099\",\"--serving-cert-file=/etc/tls/serving-cert/tls.crt\",
+    \"--serving-key-file=/etc/tls/serving-cert/tls.key\",\"--v=4\",\"--always-enable-capabilities=Ingress\"
+  ]},
+  {\"op\":\"replace\",\"path\":\"/spec/template/spec/containers/0/env\",\"value\":[
+    {\"name\":\"OPERATOR_IMAGE_VERSION\",\"value\":\"${CLUSTER_VERSION}\"},
+    {\"name\":\"KUBERNETES_SERVICE_PORT\",\"value\":\"6443\"},
+    {\"name\":\"KUBERNETES_SERVICE_HOST\",\"value\":\"${API_HOST}\"},
+    {\"name\":\"NODE_NAME\",\"valueFrom\":{\"fieldRef\":{\"fieldPath\":\"spec.nodeName\"}}},
+    {\"name\":\"CLUSTER_PROFILE\",\"value\":\"self-managed-high-availability\"},
+    {\"name\":\"PAYLOAD_OVERRIDE\",\"value\":\"/payload\"}
+  ]}
+]"
+
+# 5. Watch for proposal creation (happens after first Cincinnati update check, ~2-5 min)
+oc get proposals -n openshift-lightspeed -w
+```
+
+### Gotchas
+- **PAYLOAD_OVERRIDE is critical** — without it, the CVO reads `/release-manifests/release-metadata` (which doesn't exist in the dev image) and falls back to version `0.0.1-snapshot`, disabling all feature gates including `LightspeedProposals`.
+- **Remove the CVO deployment manifest** from `_output/payload-override/manifests/` — otherwise the CVO reconciles its own deployment and reverts the image/env changes.
+- **KUBERNETES_SERVICE_HOST must be the API hostname** (e.g., `api-int.cluster.example.com`), not a node IP. Using `fieldRef: status.hostIP` causes TLS errors.
+- **All deployment changes must be in a single `oc patch`** — sequential patches trigger rollouts that can lose env vars.
+- **Leader lease timeout** — after patching, the new pod must wait up to ~2 min for the old pod's lease to expire before it can start reconciling.
+- **Skills image** comes from the shared `agentic-skills` repo (`registry.ci.openshift.org/ocp/4.22:agentic-skills`). The Agent CR selects specific skills via `paths`.

go.mod

@@ -108,3 +108,5 @@ require (
 )
 
 replace github.com/onsi/ginkgo/v2 => github.com/openshift/onsi-ginkgo/v2 v2.6.1-0.20241205171354-8006f302fd12
+
+replace github.com/openshift/api => github.com/harche/api v0.0.0-20260414192630-b7a8e3d157cb

go.sum

@@ -70,6 +70,8 @@ github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674 h1:JeSE6pjso5THxAzdVpqr6/geYxZytqFMBCOtn/ujyeo=
 github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674/go.mod h1:r4w70xmWCQKmi1ONH4KIaBptdivuRPyosB9RmPlGEwA=
+github.com/harche/api v0.0.0-20260414192630-b7a8e3d157cb h1:8rHr8NpecxNNNjEqLJBLprSit1WFWJTEHsKePFnlURc=
+github.com/harche/api v0.0.0-20260414192630-b7a8e3d157cb/go.mod h1:pyVjK0nZ4sRs4fuQVQ4rubsJdahI1PB94LnQ8sGdvxo=
 github.com/imdario/mergo v0.3.12 h1:b6R2BslTbIEToALKP7LxUvijTsNI9TAe80pLWN2g/HU=
 github.com/imdario/mergo v0.3.12/go.mod h1:jmQim1M+e3UYxmgPu/WyfjB3N3VflVyUjjjwH0dnCYA=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
@@ -104,8 +106,6 @@ github.com/onsi/gomega v1.38.2 h1:eZCjf2xjZAqe+LeWvKb5weQ+NcPwX84kqJ0cZNxok2A=
 github.com/onsi/gomega v1.38.2/go.mod h1:W2MJcYxRGV63b418Ai34Ud0hEdTVXq9NW9+Sx6uXf3k=
 github.com/openshift-eng/openshift-tests-extension v0.0.0-20250220212757-b9c4d98a0c45 h1:hXpbYtP3iTh8oy/RKwKkcMziwchY3fIk95ciczf7cOA=
 github.com/openshift-eng/openshift-tests-extension v0.0.0-20250220212757-b9c4d98a0c45/go.mod h1:6gkP5f2HL0meusT0Aim8icAspcD1cG055xxBZ9yC68M=
-github.com/openshift/api v0.0.0-20260302174620-dcac36b908db h1:MOQ5JSIlbP4apwTrEdNpApT6PsnB0/1S6y9aKODp5Ks=
-github.com/openshift/api v0.0.0-20260302174620-dcac36b908db/go.mod h1:pyVjK0nZ4sRs4fuQVQ4rubsJdahI1PB94LnQ8sGdvxo=
 github.com/openshift/client-go v0.0.0-20260302182750-20813ce71ca6 h1:wJv4Ia+R4OxoaJcTUyvMtBc5rWFvfTiEA8d5f1MBPqI=
 github.com/openshift/client-go v0.0.0-20260302182750-20813ce71ca6/go.mod h1:3lkVff575BlbDUUhMsrD1IyvfkZ+oKUB7iZuVy1m0W0=
 github.com/openshift/library-go v0.0.0-20260303171201-5d9eb6295ff6 h1:xjqy0OolrFdJ+ofI/aD0+2k9+MSk5anP5dXifFt539Q=