Current Handover

This is the current handover for the helm-expt repository. It is intended for another engineer or agent picking up the work from public main.

For current priorities, start with Roadmap. This file is a pickup snapshot and vocabulary note, not the canonical roadmap.

For the next Codex running on a machine that can perform live Kubernetes and GitOps testing, start with:

docs/planning/large-machine-handover.md
docs/planning/large-machine-roadmap.md

Those files are stricter than this rolling handover about what "verified", "live", "all charts", and "derived variant" mean.

Repository State

The repository is a public proof corpus for turning popular public Helm charts into reviewed cub installer packages, supported base variants, rendered objects, scans, receipts, and live-test evidence.

In this handover, base variant means a render-time installer/package variant. Derived ConfigHub variant means a downstream ConfigHub variant created after a reviewed base has been uploaded, using clone/link plus approved post-render refinements. The public catalog primarily proves base variants. Derived variants are still part of the product model, but they appear after upload when a deployment needs target, environment, region, customer, namespace field, fact binding, placeholder, TransformPaths, function, gate, link, check, or observation-policy changes without re-rendering Helm.

The current public path is:

New to cub? Install the cub CLI first. You can pull and render public catalog packages without an account. Commands that save or change ConfigHub data require you to sign in.

Helm chart
  -> analyzed chart facts and control points
  -> cub installer package
  -> supported base variants that change or select the Helm-rendered object set
  -> rendered Kubernetes objects
  -> ConfigHub upload receipts
  -> optional derived ConfigHub variants for approved post-render fields, facts, targets, gates, links, checks, or observation policy
  -> operation receipts
  -> local runtime evidence
  -> GitOps/OCI runtime evidence

If a reader sees "supported variants" in generated catalog evidence, read that as "supported base variants" unless the artifact explicitly says it is a derived ConfigHub variant.

The current proof surface is:

100 charts have recipe/package proof artifacts.
20 charts are catalog-supported for the declared local-test scope.
20/20 top-20 charts have local-kind runtime receipts.
20/20 top-20 charts have ConfigHub proof receipts.
80 additional charts are proof-grade, not catalog-supported.
All non-Redis top-20 proof scripts use the shared proof kit.

For chart-recipe-variant lane coverage, use the generated lane matrix instead of chart-level shorthand:

data/outcome-coverage/summary.md

As of the current matrix, all 191 chart/base rows have Helm-equivalence plus installer setup-check evidence. ConfigHub proof, local-kind evidence, and ConfigHub OCI/Argo live proof are partial by exact variant row.

There are two live parity surfaces, and they answer different questions:

The watch and blocked rows are not currently object-set parity defects. They surface target prerequisites, hook/lifecycle routes, controller health, storage, or runtime readiness decisions that still need to be modeled or rerun.

For exact GitOps/OCI status, do not rely on copied counts in this handover. Use the generated status dashboard and outcome CSVs:

data/status-dashboard/summary.md
data/outcome-coverage/base-outcomes.csv
data/runtime-gitops/summary.md

The runtime/GitOps first wave tracks the first ten selected Argo/Flux OCI rows. The broader outcome table also includes later GitOps/OCI receipts from other live lanes. Treat both as exact chart/base evidence, not as a chart-level blanket claim.

Outcome doctrine:

Every supported Helm chart default and declared main choice should become
verifiably reproducible, ConfigHub-reviewable, live-cluster verified, and tied
to receipts.

Do not treat an activity as done just because a script, doc, generated row, or tutorial exists. The outcome must be visible in committed evidence and guarded by a verifier. For catalog-supported charts, "main choices" means the default base plus the declared supported non-default bases such as existing-secret, no-crds, server-only, ingress, HA, ClusterIP, storage, or equivalent chart choices. For derived ConfigHub variants, it means the post-render operating choices that the docs claim are supported: target, environment, region, customer, gates, facts, links, field fills, checks, and observation policy.

The current honest state is therefore:

render reproducibility: complete for current recipe variants
ConfigHub proof: partial by exact chart-recipe-variant row
local live cluster proof: partial by exact chart-recipe-variant row
GitOps/OCI live proof: partial by exact chart-recipe-variant row; use generated status for current pass, watch, blocked, and missing counts
selected live Helm-vs-ConfigHub comparison: see generated status for current pass, watch, blocked, and missing counts
live parity rerun queue: 1 GitOps/controller-health watch row, 0 render-input active rows, 0 semantic parity defects in the selected live Helm-vs-ConfigHub lane
two-cluster kind parity: 73 pass, 1 watch, 0 blocked, 0 semantic parity defects
lifecycle observation proof: cert-manager and External Secrets exact rows pass, generic hook lifecycle support remains backlog

The top-level public entry points are README.md, CATALOG.md, and the generated static site under site/.

Latest Completed Work

The proof-kit migration is complete for the current non-Redis top-20 charts: those chart proof scripts now share scripts/lib/proof-kit.mjs. Redis remains bespoke because it carries the first tutorial and user-install verification helpers.

The latest generated queues for the next proof stages are:

These files are generated and verified. Do not edit them by hand.

2026-06-13 update: Cluster Autoscaler controller-default-reviewed no longer belongs in the live rerun queue. It was converted from a misleading alias-of-default render into a values-profile rerender with autoDiscovery.clusterName=kind and awsRegion=us-east-1, then rerun through regular Helm, ConfigHub direct apply, and ConfigHub OCI/Argo. The committed receipt is:

runs/live-helm-confighub-compare/autoscaler-cluster-autoscaler-controller-default-reviewed/receipt.yaml

The useful-base realization wave now distinguishes alias bases from values-profile rerenders:

data/useful-base-realization-wave/summary.md

The compact product entry point is:

docs/user/what-you-get.md

Historical planning snapshots live under:

docs/planning/archive/

2026-06-04 Configuration-As-Data And Derived-Variant Sync

The near-term TODO list now folds in the configuration-as-data value lanes and the current cub variant command surface. See next-20-tasks.md for the active queue and issue-backlog.md for the issue mirror.

Current CLI truth:

cub variant create
cub variant promote
cub variant upload

cub variant create is the current derived-variant clone/link substrate. cub variant promote is the current upstream-to-downstream catch-up command. cub variant upload is a direct already-rendered-manifest ingestion command. cub variant release is not a current local command and should be described only as planned or candidate product work.

New issues created from the configuration-as-data / derived-variant review:

The most important gap is now explicit: the repo still needs more derived ConfigHub variants with execution receipts. Issue #144 now has a generated starting wave under data/variant-goldens/derived-expansion-wave/: 10 derived-variant work orders across Redis, Prometheus, NGINX, Grafana, and Vault. Each work order now has golden clone, mutation, and check receipt targets under receipts/<work-order>/. These are explicit proof targets, not live execution receipts.

2026-06-05 update: live derived-variant execution receipts now exist for all 10 work orders in the first derived expansion wave: NGINX, Redis, Prometheus, Grafana, and Vault. The receipts prove clone/link preservation, same final data-hash set as the reviewed base, production gates where the work order asks for them, and no Helm re-render. Grafana required one corrective update per derived variant because the initial clone replaced one duplicated 9094 port's name and protocol with confighubplaceholder; the receipts record that friction explicitly. The active ConfigHub context did not have the desired work-order targets, so these receipts intentionally stop before target binding and live apply:

runs/derived-variant-execution/nginx-prod-us-east/variant-create-receipt.yaml
runs/derived-variant-execution/nginx-customer-acme-prod/variant-create-receipt.yaml
runs/derived-variant-execution/redis-prod-us-east/variant-create-receipt.yaml
runs/derived-variant-execution/redis-staging-eu-west/variant-create-receipt.yaml
runs/derived-variant-execution/prometheus-prod-us-east/variant-create-receipt.yaml
runs/derived-variant-execution/prometheus-staging-eu-west/variant-create-receipt.yaml
runs/derived-variant-execution/grafana-prod-us-east/variant-create-receipt.yaml
runs/derived-variant-execution/grafana-customer-acme-prod/variant-create-receipt.yaml
runs/derived-variant-execution/vault-regulated-prod-us-east/variant-create-receipt.yaml
runs/derived-variant-execution/vault-staging-us-east/variant-create-receipt.yaml
npm run derived-variants:verify

Redis's ConfigHub proof receipt was also refreshed through the common top-20 ConfigHub proof lane. The Redis-specific verifier now checks the common upload.kubernetesUnitCount and serverSideVariant.downstreamSpace fields, so Redis no longer preserves the older receipt schema as a special case.

Target-bound derived-variant receipts now exist for NGINX-prod-us-east, NGINX-customer-acme-prod, MetricsServer-prod-us-east, Prometheus-prod-us-east, and Prometheus-staging-eu-west:

data/derived-variant-target-bound/summary.md
runs/derived-variant-target-bound/nginx-prod-us-east/receipt.yaml
runs/derived-variant-target-bound/nginx-customer-acme-prod/receipt.yaml
runs/derived-variant-target-bound/metrics-server-prod-us-east/receipt.yaml
runs/derived-variant-target-bound/prometheus-server-only-prod-us-east/receipt.yaml
runs/derived-variant-target-bound/prometheus-server-only-staging-eu-west/receipt.yaml
npm run derived-variants:target-bound:verify
npm run derived-variants:target-bound:summary:verify

They prove cub variant create --target, target-bound cloned workload Units, ConfigHub OCI publication, Argo CD reconciliation, Kubernetes runtime readiness, and cleanup for a small web chart, a cluster-service chart, and a server-only observability chart across production, staging, and customer-derived variants. A blocked target-bound receipt also exists for Redis-staging-eu-west; it records that the Redis staging work order needs checked namespace mutation and Redis Secret delivery before it can honestly be called target-bound live. The next derived-variant implementation step is to add those post-clone mutation/secret checks, or pick a derived variant whose declared operating change does not require them. After that, repeat the same target-bound live path for Redis or for additional derived operating variants. The Grafana placeholder drift is tracked in #156 as a follow-up issue against clone/upgrade behavior.

2026-06-03 Variant And Spreadsheet Findings

Today's review found that the public data tracks base/render variants and Helm problem-space signals, but it does not yet track derived ConfigHub variant opportunity as a first-class Top-500 metric.

Current Top-500 counts:

rows: 500
source scanned: 495
source failed: 5
current proof recipes in repo: 100
current proof recipes matched to old matrix rows: 91
no current recipe proof: 409
catalog-supported rows: 20
proof-grade rows: 71
default-only proofs: 41
multi-variant proofs: 50
matched proof variants/revisions in top-500 rows: 143
catalog-supported base variants in matched top-500 rows: 40

Current Top-500 next-action counts:

review source/current-version drift and refresh recipe if needed: 21
record target-scoped support decision and refresh live/e2e observation lane: 15
run catalog promotion review: 24
create recipe, package, variants, rendered digest, scans, and receipts: 404
add user-shaped variants before catalog promotion: 31
repair source acquisition before recipe proof: 5

Where the counts live:

Important gap:

The big Top-500 sheet does not yet count derived ConfigHub variant opportunity.
It counts current base variant proof status and maps source problem-space
complexity. Derived variant reach is now represented by goldens, the generated
derived-expansion wave, and managed-overlay examples, not yet by scaled
Top-500 catalog metrics.

The next Top-500 generator update should add generated fields or a generated companion table for:

base_variant_opportunity_count
derived_variant_opportunity_count
delivery_prerequisite_count
variant_route_mix
derived_variant_routes
problem_space_tags
recommended_variant_strategy

Recommended recommended_variant_strategy values:

needs-recipe-first
base-only
base-plus-derived
managed-overlay
delivery-prerequisite-first

The Top-500 front sheet is review.csv. The generator and verifier now check that the summary's advertised outputs exist.

Current Invariants

Keep these rules intact:

Use `cub installer` terminology consistently.
Do not claim GitOps/OCI proof unless a runtime/GitOps receipt exists.
Do not claim production support while production_disposition remains blocked.
Mutable or latest image tags are acceptable for local proof only.
Production OCI support needs image digest evidence or an explicit image override receipt.
If a choice changes Helm render inputs, object count, object shape, or lifecycle semantics, route it through the installer package/base path.
If a choice refines already-rendered ConfigHub Units through approved fields, facts, links, targets, gates, functions, checks, or observation policy, route it through derived ConfigHub variants.
Do not imply derived ConfigHub variants replace base variants for render-time object changes.
Do not describe derived ConfigHub variants as catalog-supported unless receipts prove the uploaded-base-plus-derived-variant path.
Generated data must have a verify script that fails if committed output is stale.
Every task should state the outcome it will prove, the evidence artifact that proves it, and the verifier that keeps it current.

Variant Vocabulary

Use this wording consistently in user-facing docs:

Short rule:

Helm render or object shape changes -> base variant.
Approved post-render refinement changes -> derived ConfigHub variant.
Delivery blocker remains -> delivery prerequisite.

Important Generated Data

Use these generated summaries together:

User Documentation

The primary user docs are under docs/user. They should stay short, plain, and concrete. Do not move generated proof transcripts into the user path.

Important user guides:

Tests And Commands

Start with tests/npm-scripts.md for the full command map.

For normal changes:

npm run docs:verify
npm run installer:command-surface:verify

For generated data changes:

npm run attack-plan:verify
npm run runtime-gitops:wave:verify
npm run hooks:lifecycle:verify
npm run image-digests:workdown:verify
npm run next-ten:waves:verify
npm run top20:verify-local-e2e
npm run production:disposition:verify
npm run catalog:wave2:verify
npm run top20:latest-refresh:verify
npm run top20:latest-candidates:verify
npm run top20:latest-promotion-readiness:verify
npm run site:verify

Before merging broad changes:

npm run verify

The full verify chain is expected to pass on a clean checkout.

Suggested Next Tasks

Use next-20-tasks.md as the single active TODO queue. The headline order is:

1. Make cub variant create current and explicit in docs, Tutorial 4, UX proposals, and command-surface verification (#143).
2. Extend the target-bound derived-variant lane beyond the first NGINX live receipt, starting with Redis and Prometheus (#144).
3. Prove promotion and environment management with derived ConfigHub variants (#145).
4. Keep the closed Helm import path contract (#76) verifier-backed while the downstream cub installer import helm product command remains future work.
5. Continue wave-2 base-variant promotion, production support decisions, target facts, GitOps/Argo proof, release/OCI semantics, promotion UI expectations, fleet inventory, fleet mutation, policy/security posture, and impact analysis in the order listed in next-20-tasks.md.

Operating Cautions

Do not add another planning document when an existing generated work queue can be refreshed instead.

Do not mark a catalog entry production-supported because it has local-kind evidence or accepted dispositions. Production support needs a final target-scoped decision that records the support scope, required live checks, image policy, lifecycle policy, and runtime/GitOps evidence.

Do not make the user-facing docs longer to explain internal proof machinery. Link to generated evidence from the docs instead.

Do not file issues outside this repository without explicit approval.