Merge pull request #14 from mayur-tolexo/docs/release-v0.1.1-prep

v0.1.1: honest confidence + bands + docs (re-target to main)

Author: mayur-tolexo

CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to kubetidy are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html) (pre-1.0: minor = features, patch =
+fixes/UX).
+
+## [Unreleased] — v0.1.1
+
+The operator's Tier‑0 history now actually reaches a scan, and confidence is honest about how
+much data backs each recommendation. Found and fixed against a real cluster.
+
+### Fixed
+- **Operator history was silently discarded.** `UsageProfile` declares a status subresource, so
+  the operator's `Save` (plain `Create`/`Update`) persisted empty profile shells — sample count,
+  per-container percentiles and histograms were dropped. `Save` now writes the status subresource
+  (`UpdateStatus`). Profiles created before the fix refill in place on the next ticks.
+- **Scan ignored the operator.** `selectUsageProvider` never selected the operator tier; it went
+  straight from Prometheus to the metrics-server snapshot. It now prefers the operator's history
+  (Tier 0) when `UsageProfile`s exist, with a per-workload metrics-server fallback so coverage is
+  not lost while the operator warms up.
+- Sub-hour windows render as `12m` instead of a broken-looking `0h`.
+
+### Changed
+- **Confidence is now data-maturity gated.** Time-series tiers (operator/Prometheus/OpenCost)
+  earn their high base only as window *and* sample coverage accumulate, so a freshly-installed
+  operator with two readings reads **low**, not a false ~85%.
+- **Confidence is shown as bands** (`▒ low · ▓ med · █ high`) instead of a false-precision
+  percentage; the exact % remains under `--explain`.
+- The scan `data:` banner reports the tier that actually backed the findings (dominant tier),
+  not the provider's declared tier — honest during operator warm-up.
+
+## [0.1.0] — 2026-06-01
+
+Initial public release.
+
+### Added
+- `kubectl tidy scan` — read-only efficiency score, dollar waste, and rightsizing
+  recommendations with confidence + evidence; `--explain`, `--output json`.
+- `kubectl tidy diff` — exact, reversible `kubectl patch` per recommendation.
+- `kubectl tidy pr` — GitOps change set (patch files + Markdown PR body).
+- `kubectl tidy init` / `uninstall` — install/remove the CRDs + read-only operator from
+  binary-embedded manifests.
+- Data ladder: metrics-server snapshot, Prometheus (auto-detected, Tier 1), and the in-cluster
+  **kubetidy operator** (Tier 0 history with no Prometheus).
+- **OpenCost** integration for precise allocated cost (auto-detected, or `--opencost-url`; Tier 2).
+- CRDs: `UsageProfile`, `ClusterUsageSummary`, `Recommendation`.
+- Install via **krew**, `curl | sh`, or pre-built archives; tagged GitHub release pipeline
+  (GoReleaser) with an auto-rendered krew manifest.
+
+[Unreleased]: https://github.com/mayur-tolexo/kubetidy/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/mayur-tolexo/kubetidy/releases/tag/v0.1.0

README.md

@@ -31,6 +31,10 @@ and **acting on** the recommendations. kubetidy is built around trust:
   monthly dollar figure.
 - **Every number shows its work.** `--explain` reveals the exact query, window, sample
   count, variance, and policy behind each recommendation.
+- **Confidence you can trust.** Each recommendation is graded **▒ low · ▓ med · █ high**, and
+  the grade *grows as history accumulates* — a freshly-installed operator with a couple of
+  readings reads **low**, never a false "85%". It only earns **high** once a real window of
+  samples backs it (`--explain` shows the exact %).
 - **Read-only and reversible by design.** kubetidy never mutates your cluster. `diff` prints
   the exact, reversible `kubectl patch`; `pr` writes a GitOps change set you review and merge.
 
@@ -284,10 +288,13 @@ All defaults are surfaced in `--explain` and overridable. The number is never a
 
 ## Status
 
-🚧 **Active development.** `scan`, `diff`, `pr`, and `init` work today, with a read-only
-operator, Prometheus auto-detection, and OpenCost auto-detection for precise cost (Tier 2). See
-the [roadmap](ROADMAP.md) for what is next (guarded apply, multi-cluster), and
-[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the high-level design and flow diagrams.
+🚀 **v0.1.0 released** — install via [krew](#install), `curl | sh`, or pre-built archives.
+
+`scan`, `diff`, `pr`, and `init` work today, with a read-only operator that records real
+Tier‑0 history (no Prometheus), Prometheus auto-detection (Tier 1), OpenCost auto-detection for
+precise cost (Tier 2), and confidence grading that scales with data maturity. See the
+[changelog](CHANGELOG.md) for what's new, the [roadmap](ROADMAP.md) for what's next (guarded
+apply, multi-cluster), and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the design.
 
 ## Contributing
 

ROADMAP.md

@@ -50,9 +50,14 @@ This roadmap is intentionally public and open for discussion — please weigh in
       binary; no manual `kubectl apply`.
 - [ ] Guarded `apply` with auto-rollback on SLO regression
 - [x] Tier 2: OpenCost integration for precise allocated cost (auto-detected, or `--opencost-url`)
+- [x] **Recommendation CRDs** — the operator writes a per-workload `Recommendation` (the LLM
+      target; rules-engine source today). Multi-cluster aggregation still to come.
+- [x] **Confidence that grows with data** — recommendations are graded low/med/high and gated
+      on data maturity, so warm-up history isn't passed off as high-confidence.
 - [ ] Accountability: per-team showback + budgets
-- [ ] Recommendation CRDs + multi-cluster aggregation (continuous, in-cluster)
+- [ ] Multi-cluster aggregation (continuous, in-cluster)
 - [ ] Cleanup detectors (orphaned services/PVCs, idle namespaces, zombie workloads)
+- [ ] Interactive `scan -i` TUI to browse/filter recommendations and drill into `--explain`
 
 ## 💼 Commercial (open-core)
 

docs/ARCHITECTURE.md

@@ -112,6 +112,24 @@ read-only with respect to workloads — it never evicts or resizes. `kubectl tid
 (`internal/installer`) applies the embedded CRD + operator manifests so setup is a single CLI
 command. See [design/operator.md](design/operator.md).
 
+`UsageProfile` (like the other CRDs) declares a **status subresource**, so the store writes spec
+via `Create`/`Update` and the recorded history via a follow-up `UpdateStatus` — a plain update
+silently drops `status`. On the read side the scan prefers the operator (`usage.DetectOperator`
+→ `NewOperatorProvider`) and wraps it in a `fallbackProvider` so workloads the operator has not
+profiled yet are still covered by the metrics-server snapshot (no coverage regression during
+warm-up).
+
+## Confidence and the honest tier banner
+
+`internal/rightsizer` grades each recommendation with a **data-maturity** model: snapshot/static
+tiers use a fixed low base, while time-series tiers (operator, Prometheus, OpenCost) earn their
+high base only as `maturity = min(window/72h, log10(samples)/log10(8000))` approaches 1, then
+lose ground to observed variance. So two readings over a few minutes score "low", not a
+misleading "85%". The CLI surfaces this as bands (low/med/high); the exact percentage is in
+`--explain`. The scan's `data:` banner reports the tier that **actually** backed the findings
+(the dominant tier of the recommendations), not the provider's declared tier — so during
+operator warm-up it honestly reads `snapshot` until profiles mature.
+
 ```mermaid
 flowchart LR
     timer([every scrape interval]) --> sample[sample metrics-server]

internal/cli/orchestration_test.go

@@ -289,8 +289,11 @@ func TestSelectUsageProviderPrefersOperatorWhenProfilesExist(t *testing.T) {
 	if p.Name() != "kubetidy operator" {
 		t.Errorf("provider = %q, want kubetidy operator (Tier 0)", p.Name())
 	}
-	if !strings.Contains(strings.Join(warnings, " "), "operator history") {
-		t.Errorf("warnings = %v, want an operator-history note", warnings)
+	// No blanket note is emitted for the operator: the data banner states the tier and the
+	// per-recommendation evidence shows any snapshot fallback, so a "using operator" note would
+	// overclaim during warm-up.
+	if strings.Contains(strings.Join(warnings, " "), "operator") {
+		t.Errorf("did not expect an operator note, got %v", warnings)
 	}
 }
 

internal/cli/scan.go

@@ -156,7 +156,9 @@ func selectUsageProvider(clients *kube.Clients, f *scanFlags, warnings *[]string
 	// so workloads the operator has not profiled yet are still covered (no coverage regression
 	// while the operator warms up).
 	if usage.DetectOperator(clients.Dynamic) {
-		*warnings = append(*warnings, "using kubetidy operator history (Tier 0); metrics-server snapshot covers any not-yet-profiled workloads")
+		// No note here: the data banner already states the tier, and the per-recommendation
+		// evidence line shows which workloads (if any) fell back to a snapshot. A blanket
+		// "using operator history" note overclaims while the operator is still warming up.
 		return usage.NewFallbackProvider(
 			usage.NewOperatorProvider(clients.Dynamic),
 			usage.NewMetricsServerProvider(clients.Metrics),

internal/model/model.go

@@ -176,6 +176,31 @@ type Confidence struct {
 // Percent returns the confidence as an integer percentage 0..100.
 func (c Confidence) Percent() int { return int(c.Score*100 + 0.5) }
 
+// ConfidenceBand is a coarse, human-facing bucket for a confidence score. A precise percentage
+// implies false precision ("85%" from two samples is misleading), so the UI leads with the band
+// and keeps the number for detail views.
+type ConfidenceBand string
+
+// The three confidence buckets, from least to most trustworthy.
+const (
+	ConfidenceLow    ConfidenceBand = "low"
+	ConfidenceMedium ConfidenceBand = "med"
+	ConfidenceHigh   ConfidenceBand = "high"
+)
+
+// Band buckets the score: < 0.60 low, < 0.80 medium, otherwise high. The low cutoff sits above
+// the snapshot ceiling (0.60) so a single-snapshot recommendation never reads above "low".
+func (c Confidence) Band() ConfidenceBand {
+	switch {
+	case c.Score < 0.60:
+		return ConfidenceLow
+	case c.Score < 0.80:
+		return ConfidenceMedium
+	default:
+		return ConfidenceHigh
+	}
+}
+
 // Recommendation is the central, action-ready unit kubetidy produces. The MVP only reads,
 // but this carries enough to generate a patch later (target ref, container, current vs
 // proposed), so the future action layer is a new consumer, not a rewrite.

internal/model/model_test.go

@@ -64,3 +64,22 @@ func TestDefaultPolicy(t *testing.T) {
 		t.Error("default policy should be downsize-only on snapshot data")
 	}
 }
+
+func TestConfidenceBand(t *testing.T) {
+	cases := []struct {
+		score float64
+		want  ConfidenceBand
+	}{
+		{0.05, ConfidenceLow},
+		{0.59, ConfidenceLow},
+		{0.60, ConfidenceMedium},
+		{0.79, ConfidenceMedium},
+		{0.80, ConfidenceHigh},
+		{0.99, ConfidenceHigh},
+	}
+	for _, c := range cases {
+		if got := (Confidence{Score: c.score}).Band(); got != c.want {
+			t.Errorf("Band(%.2f) = %q, want %q", c.score, got, c.want)
+		}
+	}
+}

internal/report/report.go

@@ -163,12 +163,12 @@ func writeRecommendations(b *strings.Builder, recs []model.Recommendation, opts
 	// Flushing to an in-memory strings.Builder cannot fail.
 	_, _ = fmt.Fprintf(tw, "  WORKLOAD\tCPU\tMEM\tSAVINGS\tCONF\n")
 	for _, rec := range recs {
-		_, _ = fmt.Fprintf(tw, "  %s\t%s\t%s\t%s\t%d%%\n",
+		_, _ = fmt.Fprintf(tw, "  %s\t%s\t%s\t%s\t%s\n",
 			workloadLabel(rec),
 			cpuTransition(rec),
 			memTransition(rec),
 			savingsCell(rec),
-			rec.Confidence.Percent(),
+			confidenceCell(rec),
 		)
 	}
 	_ = tw.Flush()
@@ -199,7 +199,7 @@ func writeRecommendations(b *strings.Builder, recs []model.Recommendation, opts
 func writeLegend(b *strings.Builder, opts Options) {
 	lines := []string{
 		"CPU/MEM = current → proposed request · SAVINGS = $/mo (↑ grow = reliability, not a saving)",
-		"conf = confidence in this recommendation; higher data tiers (Prometheus, OpenCost) score higher.",
+		"CONF = confidence: ▒ low · ▓ med · █ high — grows with data history (tier, window, samples). --explain shows the %.",
 	}
 	for _, l := range lines {
 		if opts.Color {
@@ -234,6 +234,20 @@ func savingsCell(rec model.Recommendation) string {
 	return fmt.Sprintf("%s/mo", formatDollarsAbs(rec.MonthlySavings))
 }
 
+// confidenceCell renders the qualitative confidence band with a shaded glyph that reads as a
+// fill level even without color. A precise percentage is intentionally omitted here (it implies
+// false precision); the number is available under --explain.
+func confidenceCell(rec model.Recommendation) string {
+	switch rec.Confidence.Band() {
+	case model.ConfidenceHigh:
+		return "█ high"
+	case model.ConfidenceMedium:
+		return "▓ med"
+	default:
+		return "▒ low"
+	}
+}
+
 // JSON renders a stable machine-readable schema of the scan result.
 //
 // The schema is exactly the JSON encoding of model.ScanResult: an object with
@@ -265,7 +279,7 @@ func Explain(w io.Writer, rec model.Recommendation) error {
 	} else {
 		fmt.Fprintf(&b, "  savings:  %s / month\n", formatSignedDollars(rec.MonthlySavings))
 	}
-	fmt.Fprintf(&b, "  confidence:  %d%% (%s)\n", rec.Confidence.Percent(), rec.Confidence.Reason)
+	fmt.Fprintf(&b, "  confidence:  %s (%d%%) — %s\n", rec.Confidence.Band(), rec.Confidence.Percent(), rec.Confidence.Reason)
 	fmt.Fprintf(&b, "  tier:  %s\n", rec.Tier.String())
 	if rec.Evidence != "" {
 		fmt.Fprintf(&b, "  evidence:  %s\n", rec.Evidence)

internal/report/report_test.go

@@ -172,8 +172,8 @@ func TestTableRecommendationRow(t *testing.T) {
 	if !strings.Contains(out, "$210/mo") {
 		t.Errorf("missing savings\n--- got ---\n%s", out)
 	}
-	if !strings.Contains(out, "96%") {
-		t.Errorf("missing confidence\n--- got ---\n%s", out)
+	if !strings.Contains(out, "█ high") {
+		t.Errorf("missing confidence band\n--- got ---\n%s", out)
 	}
 	// Evidence is indented under the row with the └ marker.
 	if !strings.Contains(out, "    └ P95 cpu 280m") {
@@ -256,7 +256,7 @@ func TestTableLegendShown(t *testing.T) {
 		t.Fatalf("Table: %v", err)
 	}
 	out := buf.String()
-	if !strings.Contains(out, "conf = confidence in this recommendation") {
+	if !strings.Contains(out, "CONF = confidence:") {
 		t.Errorf("missing legend\n--- got ---\n%s", out)
 	}
 }
@@ -328,7 +328,7 @@ func TestExplain(t *testing.T) {
 		"cpu:  2000m → 320m",
 		"mem:  4Gi → 1.1Gi",
 		"savings:  $210 / month",
-		"confidence:  96% (tier 1, 14d, low variance)",
+		"confidence:  high (96%) — tier 1, 14d, low variance",
 		"tier:  1 (Prometheus)",
 		"evidence:  P95 cpu 280m",
 		"derivation:",