feat(diagnostics): Add Helm upgrade failure triage

Add a HelmRelease diagnostic entrypoint and Helm-aware evidence metadata so agents can distinguish rollout evidence from missing Helm CLI or release manifest evidence.

Document the user story for diagnosing Helm upgrade failures when users no longer have Helm CLI output, including validated kind scenarios and acceptance criteria.

Author: Colvin-Y

AI_CONTRACT.md

@@ -223,6 +223,20 @@ relationships use `provenance.sourceType=label_evidence`,
 `provenance.state=inferred`, and a numeric confidence. Treat them as strong or
 weak ownership hints until exact Helm release manifest evidence is collected.
 
+For Helm upgrade failures, the diagnostic graph describes current Kubernetes
+state plus Helm metadata already visible in the cluster. It cannot observe Helm
+CLI stderr, chart rendering, values schema validation, repository/client
+authentication, hook execution semantics, or the original failure hidden by
+`--atomic` rollback unless the user provides that output. When Helm evidence is
+present, agents should expect:
+
+- a `helm_cli_output_not_observed` warning
+- a `helm_manifest_evidence_not_collected` warning for label-derived ownership
+- `helm_cli_output` and `helm_release_manifest` entries in `degradedSources`
+- `HelmOwnershipEvidence` / `HelmChartEvidence` entries in `rankedEvidence`
+- `helm_ownership_conflict` conflicts when one resource points at multiple
+  candidate releases
+
 AI-Agent code should assume these meanings are stable, even if the set of returned nodes varies by policy.
 
 ## What AI-Agent code should treat as optional

Makefile

@@ -44,7 +44,7 @@ DAEMON_CONFIG_OVERRIDES = $(CLI_CONFIG_OVERRIDES) $(call make_arg,SERVER_ADDR,ad
 CLI_CONFIG_ARGS = $(if $(CONFIG),--config "$(CONFIG)" $(CLI_CONFIG_OVERRIDES),--kubeconfig "$(KUBECONFIG)" --cluster "$(CLUSTER)" --context-namespaces "$(CONTEXT_NAMESPACES)" --workload-resources "$(WORKLOAD_RESOURCES)" --controller-rules "$(CONTROLLER_RULES)" --bootstrap-timeout "$(BOOTSTRAP_TIMEOUT)")
 DAEMON_CONFIG_ARGS = $(if $(CONFIG),--config "$(CONFIG)" $(DAEMON_CONFIG_OVERRIDES),--kubeconfig "$(KUBECONFIG)" --cluster "$(CLUSTER)" --context-namespaces "$(CONTEXT_NAMESPACES)" --workload-resources "$(WORKLOAD_RESOURCES)" --controller-rules "$(CONTROLLER_RULES)" --addr "$(SERVER_ADDR)" --bootstrap-timeout "$(BOOTSTRAP_TIMEOUT)" --poll-interval "$(POLL_INTERVAL)")
 
-.PHONY: build build-daemon build-viewer docker-build owl test verify ci ci-go ci-helm ci-binaries ci-client ci-visualize run serve status status-server list-entities-server get-entity-server list-relations-server neighbors-server expand-node-server collapse-node-graph observe-status diagnose-pod diagnose-workload diagnose-pod-server diagnose-workload-server visualize visualize-go visualize-check live-check verify-live require-kubeconfig require-entry
+.PHONY: build build-daemon build-viewer docker-build owl test verify ci ci-go ci-helm ci-binaries ci-client ci-visualize run serve status status-server list-entities-server get-entity-server list-relations-server neighbors-server expand-node-server collapse-node-graph observe-status diagnose-pod diagnose-workload diagnose-helm-release diagnose-pod-server diagnose-workload-server visualize visualize-go visualize-check live-check verify-live require-kubeconfig require-entry
 
 build:
 	mkdir -p bin
@@ -174,6 +174,15 @@ diagnose-workload: build require-kubeconfig require-entry
 	  --max-depth "$(MAX_DEPTH)" \
 	  --storage-max-depth "$(STORAGE_MAX_DEPTH)" $(make_diagnostic_budget_args)
 
+diagnose-helm-release: build require-kubeconfig require-entry
+	$(BINARY) \
+	  $(CLI_CONFIG_ARGS) \
+	  --diagnose-helm-release \
+	  --namespace "$(NAMESPACE)" \
+	  --name "$(NAME)" \
+	  --max-depth "$(MAX_DEPTH)" \
+	  --storage-max-depth "$(STORAGE_MAX_DEPTH)" $(make_diagnostic_budget_args)
+
 diagnose-pod-server: build require-entry
 	$(BINARY) \
 	  --server "$(SERVER_URL)" \

QUICKSTART.md

@@ -556,6 +556,22 @@ When resources carry standard Helm metadata, diagnostic graphs can also include
 `installs_chart` edges. These edges are label evidence with confidence scores,
 not exact Helm manifest membership.
 
+For a failed Helm upgrade where the user does not have CLI output, start from
+the release and inspect current cluster evidence:
+
+```bash
+kubernetes-ontology \
+  --server "http://127.0.0.1:18080" \
+  --diagnose-helm-release \
+  --namespace default \
+  --name my-release
+```
+
+The response can identify release-owned resources, rollout blockers, Events,
+and probable chart ownership. It cannot observe Helm template, values,
+repository, client, hook, or `--atomic` rollback errors unless the user provides
+the Helm output.
+
 Pod-centered diagnostic queries keep shared nodes bounded by default. For
 example, a pod's `ServiceAccount` is shown, but the traversal does not continue
 through that ServiceAccount to every other pod using it. Use

README.md

@@ -112,6 +112,32 @@ Resources labeled with standard Helm metadata produce `HelmRelease` and
 `installs_chart` edges with `label_evidence` provenance and confidence scores.
 These are ownership hints from labels, not exact manifest membership.
 
+### Helm Upgrade Failure Triage
+
+When a user only says "helm upgrade failed" and does not have the Helm CLI
+output, `kubernetes-ontology` can still diagnose the current cluster state for
+that release:
+
+```bash
+kubernetes-ontology \
+  --server "http://127.0.0.1:18080" \
+  --diagnose-helm-release \
+  --namespace default \
+  --name my-release
+```
+
+The response expands the probable release-owned resources and chart evidence.
+It also marks the missing Helm-side evidence explicitly:
+
+- `helm_cli_output_not_observed`: template, values, repository, client, hook,
+  and `--atomic` rollback errors are outside current Kubernetes object state.
+- `helm_manifest_evidence_not_collected`: default Helm ownership is label and
+  annotation evidence, not exact release manifest membership.
+
+For rollout failures that reached the cluster, follow the release graph into
+the affected Workload or Pod diagnostic. For render/client failures, ask the
+user to paste the `helm upgrade` stderr or `helm status/history` output.
+
 ## Agent Onboarding
 
 This repository provides a Codex-style skill:
@@ -390,6 +416,16 @@ Diagnose a pod:
   --max-edges 400
 ```
 
+Diagnose a Helm release after a failed upgrade:
+
+```bash
+./bin/kubernetes-ontology \
+  --server "http://127.0.0.1:18080" \
+  --diagnose-helm-release \
+  --namespace default \
+  --name my-release
+```
+
 Diagnostic responses include additive `partial`, `warnings`, `budgets`,
 `rankedEvidence`, `degradedSources`, and `conflicts` fields. Agents should use
 those fields to distinguish bounded evidence from complete cluster truth.

README.zh-CN.md

@@ -70,6 +70,21 @@ Helm 关系会以 `managed_by_helm_release` 和 `installs_chart` 边呈现，
 provenance 是 `label_evidence`，并带 confidence。它们是标签证据下的归属
 提示，不等同于精确 manifest 成员关系。
 
+如果用户说“helm upgrade 失败了”但没有 Helm CLI 输出，可以先从当前集群状态
+诊断 release：
+
+```bash
+kubernetes-ontology \
+  --server "http://127.0.0.1:18080" \
+  --diagnose-helm-release \
+  --namespace default \
+  --name my-release
+```
+
+返回结果会展示 release 可能管理的资源、chart 证据、rollout 阻塞点和事件。
+同时也会明确标记：template、values、repo/client、hook、`--atomic` rollback
+原始错误需要用户提供 Helm stderr/status/history 才能判断。
+
 运行时支持：
 
 - 启动时全量快照
@@ -313,6 +328,16 @@ OpenKruise，这是正常情况，不需要为此中断启动。
   --max-edges 400
 ```
 
+诊断 Helm release：
+
+```bash
+./bin/kubernetes-ontology \
+  --server "http://127.0.0.1:18080" \
+  --diagnose-helm-release \
+  --namespace default \
+  --name my-release
+```
+
 诊断返回会额外包含 `partial`、`warnings`、`budgets`、
 `rankedEvidence`、`degradedSources` 和 `conflicts`。Agent 应优先读取
 这些字段，区分“有边界的证据图”和“完整集群事实”。

cmd/kubernetes-ontology/main.go

@@ -49,6 +49,7 @@ func main() {
 	var statusOnly bool
 	var diagnosePod bool
 	var diagnoseWorkload bool
+	var diagnoseHelmRelease bool
 	var observeDuration time.Duration
 	var pollInterval time.Duration
 	var streamMode string
@@ -92,6 +93,7 @@ func main() {
 	flag.BoolVar(&statusOnly, "status", false, "Alias for --status-only")
 	flag.BoolVar(&diagnosePod, "diagnose-pod", false, "Diagnose a Pod by --namespace and --name")
 	flag.BoolVar(&diagnoseWorkload, "diagnose-workload", false, "Diagnose a Workload by --namespace and --name")
+	flag.BoolVar(&diagnoseHelmRelease, "diagnose-helm-release", false, "Diagnose a Helm release by --namespace and --name")
 	flag.DurationVar(&observeDuration, "observe-duration", 0, "Keep observing the cluster for this duration before printing status or query output")
 	flag.DurationVar(&pollInterval, "poll-interval", 10*time.Second, "Polling interval used with --observe-duration")
 	flag.StringVar(&streamMode, "stream-mode", string(collectk8s.StreamModePolling), "Continuous update stream mode for --observe-duration: informer or polling")
@@ -140,8 +142,14 @@ func main() {
 	if terminalKindsDisable {
 		expandTerminalNodes = true
 	}
-	if diagnosePod && diagnoseWorkload {
-		err := fmt.Errorf("only one of --diagnose-pod or --diagnose-workload may be set")
+	diagnoseModeCount := 0
+	for _, enabled := range []bool{diagnosePod, diagnoseWorkload, diagnoseHelmRelease} {
+		if enabled {
+			diagnoseModeCount++
+		}
+	}
+	if diagnoseModeCount > 1 {
+		err := fmt.Errorf("only one of --diagnose-pod, --diagnose-workload, or --diagnose-helm-release may be set")
 		if machineErrors {
 			writeMachineError(os.Stderr, err)
 		} else {
@@ -155,6 +163,9 @@ func main() {
 	if diagnoseWorkload {
 		entryKind = "Workload"
 	}
+	if diagnoseHelmRelease {
+		entryKind = "HelmRelease"
+	}
 
 	if collapseNode {
 		if err := collapseGraphFile(graphFile, entityID); err != nil {

docs/design/README.md

@@ -14,7 +14,9 @@ Recommended reading order:
 2. `current-state-and-next-steps.md` records the current implementation state.
 3. `open-source-mvp-plan.md` defines the open-source MVP boundary.
 4. `kubernetes-semantic-kernel-evolution.md` gives the long-term architecture.
-5. `continuous-runtime-technical-design.md` and
+5. `helm-upgrade-failure-user-story.md` standardizes the Helm upgrade failure
+   scenario where the user no longer has Helm CLI output.
+6. `continuous-runtime-technical-design.md` and
    `continuous-runtime-progress-snapshot.md` capture runtime design history.
 
 Detailed research notes are kept under `research/` so the design rationale and