feat(issues): add Kyverno as a source for /api/issues + MCP issues tool (T11)

[nadaverell]

Wave 2 / Phase 4c. Adds Kyverno PolicyReport findings as a first-class source for /api/issues and the MCP issues tool, with explicit lifecycle signaling so an empty result is never ambiguous.

What lands

pkg/policyreports/index.go — Index over PolicyReport / ClusterPolicyReport CRs. Indexed by group/Kind/ns/name (group first because group AND namespace can each be empty independently — encoding group last leaves a cluster-scoped CRD key ambiguous with a namespaced core-group key under any 3-part parse). Group derived from scope.apiVersion AND results[].resources[].apiVersion so per-result resources targeting multiple subjects each get the right group.

Subject struct carries {Group, Kind, Namespace, Name} — Group propagates all the way through to Issue.Group via fromKyverno in internal/issues/issues.go.

internal/issues/ — new SourceKyverno constant, composer integration, Compose honors ?source=kyverno filter.

internal/server/issues_handler.go — REST /api/issues?source=kyverno returns Kyverno-only findings.

internal/mcp/tools.go::handleIssues — MCP issues tool accepts source=kyverno (and include_kyverno=true for additive opt-in).

Lifecycle signaling

Empty Kyverno results were silently empty whether Kyverno was unavailable, warmup-deferred, or genuinely had no findings — agents had no way to tell. Added k8s.KyvernoStatus enum (not_installed / deferred / warmup / ready) backed by an atomic.Value. Both REST and MCP emit meta.kyverno: "<status>" on the response only when the caller opted into Kyverno (source=kyverno or include_kyverno=true). Default responses skip the meta to keep payload lean.

Race protection: Reset vs Warmup

The Reset / Warmup interaction needed two rounds of hardening:

1. kyvernoWarmupGen (atomic.Int64) bumped inside ResetPolicyReportIndex; all setDecision / publishReady writes inside the Warmup lambda check gen under policyReportMu before storing.
2. Snapshot of (policyReportInit, kyvernoWarmupGen) happens UNDER policyReportMu BEFORE Do() — closes the window where the lambda could capture the post-Reset gen and still write OLD-cluster data with the NEW gen.

A -race torture test (4 resetters × 4 snapshotters × 500 iterations) plus a structural-invariant test pin the design.

Source filter contract

source=X filters to ONLY the listed sources. include_X=true adds X to the default problem + condition set without silencing. Docs in issues_handler.go, the MCP issues tool description, and the wantSource implementation comment all now spell this out — earlier wording (incl. the MCP jsonschema string "Sources are AND'd; opting one in does not silence the defaults") was misleading and asserted the opposite behavior.

Wire-surface alignment with T6

Mirrors PR #721's speculative-surface trim of pkg/resourcecontext/types.go — drops ContextRef.Reason/Source/Confidence, the RefReason/RefSource enums, ResourceContext.Truncated, and two unused OmittedReason values. T11 doesn't reference the deleted fields; this keeps the shared types in sync across the wave-2 PRs so they don't conflict on merge regardless of order. Retained OmittedCacheCold + OmittedNotInstalled per the explicit TODO(T10) in internal/k8s/policy_reports.go that plans to populate these when the diagnostic-tier Kyverno consumer arrives.

Verification

go vet ./... + go test -count=1 -race ./internal/k8s/... + full go test -count=1 ./... all green. Tests pin: group propagation from scope.apiVersion AND per-result resources[].apiVersion, Issue.Group via fromKyverno, status enum lifecycle, gen monotonicity, stale-gen write skip, Once/gen atomic snapshot under race.

---

Note

Medium Risk
Adds a new Kyverno-backed issues source and modifies PolicyReport warmup/reset concurrency with new lifecycle state tracking; correctness depends on atomic/generation logic and could affect issue completeness or stale state across cluster switches.

Overview
Adds Kyverno PolicyReport/ClusterPolicyReport findings as an opt-in kyverno source for the unified issues surfaces (/api/issues and the MCP issues tool), mapping fail/error → critical, warn → warning, and omitting pass/skip, while propagating the subject’s API group to avoid kind collisions.

Introduces Kyverno index lifecycle reporting (not_installed/deferred/warmup/ready) and returns it as meta.kyverno only when Kyverno is requested (include_kyverno=true or source=kyverno), plus clarifies/enforces that source= is a filter (not additive) and adds include_kyverno for “defaults + kyverno” behavior.

Hardens PolicyReport warmup vs context-switch reset with generation-guarded atomic writes and adds extensive unit tests (issues composition, group keying/index enumeration, lifecycle transitions, and race-protection), along with documentation updates noting Kyverno support and issues mapping.

^{Reviewed by Cursor Bugbot for commit e92001b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 37c40a2. Configure here.}