Introduction To The Harness

UNOFFICIAL/EXPERIMENTAL

This document explains how a new Helm chart becomes a ConfigHub cub installer recipe in this repo, and how decisions are made about where each part of the install and customization process belongs.

This is not one prompt.
It is an AI-assisted engineering workflow with mechanical proof.

AI helps analyze public Helm charts, draft artifacts, and spot control points. The workflow decides whether the result is believable by comparing outputs, binding digests, running scans, checking gates, and recording receipts.

What To Say When Someone Asks "What Prompt Did You Use?"

Say this:

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.

We do not generate recipes from one prompt. We use AI as an analyst and code
assistant inside a deterministic recipe-construction workflow. The workflow
decides where each Helm behavior belongs, then cub installer and verifiers prove
the result against regular Helm output.

Or shorter:

The prompt is less important than the workflow. The AI follows a chart-import
checklist, classifies Helm behavior into installer/ConfigHub control points,
drafts recipe and variant artifacts, then the repo proves or rejects them with
Helm equivalence, digest checks, scans, gates, and live receipts.

Core Flow

The workflow turns this:

public Helm chart

into this:

1 Helm chart version
-> 1 core installer recipe/package
-> N curated install variants
-> immutable rendered revisions
-> Helm-equivalence receipts, scans, gates, and live observations

The default rule is:

Recipe = reusable chart definition.
Variant = chosen install shape.
Revision = exact rendered object set.
Derived ConfigHub variant = post-upload clone/refinement when no new Helm render is needed.
Receipt = proof of what happened.

The lifecycle doctrine is:

acquire and pin
render and capture
shape base variants
scan and gate
settle prerequisites
publish and deploy
observe and operate

Those seven stages are the stable map for hooks, CRDs, generated values, target facts, overlays, GitOps handoff, and live observations. See Seven-Stage Helm Lifecycle.

How A New Recipe Is Generated

1. Pick a public Helm chart and exact version.
2. Lock the chart source and dependency closure.
3. Render with regular Helm under pinned inputs.
4. Analyze the chart for control points: values, dependencies, capabilities, hooks, CRDs, generated facts, target facts, raw manifests, tpl, RBAC, webhooks, storage, and runtime requirements.
5. Draft the core recipe and value model.
6. Choose a small set of useful install variants.
7. Render immutable variant revisions.
8. Compare cub installer setup output to regular Helm output.
9. Scan and gate the exact rendered objects.
10. Upload or publish through ConfigHub paths when that lane is being proven.
11. Record receipts and live observations.
12. Promote only when the variant is simple, useful, and mechanically proven.

The AI can help with steps 4-7 and with writing artifacts, but the workflow checks steps 8-12.

Where Pieces Go

The goal is to absorb Helm weirdness into the model, not hide it in prose. If the chart does something unusual, it should have a named home, a policy, a status, and a proof artifact.

Helm Hook Policy

Helm hooks are cluster-dependent lifecycle actions. They are not ordinary configuration objects.

The hard boundary is:

Chart -> recipe -> variant -> rendered normal objects can be deterministic.
Hook execution depends on the live target cluster.

That dependency is expected. Hook Jobs and hook-managed objects can depend on RBAC, CRDs, admission webhooks, existing Secrets or ConfigMaps, StorageClasses, PVCs, API versions, release history, upgrade/install phase, and delete policy. ConfigHub does not pretend that live execution is deterministic. It makes that cluster dependence explicit before install.

The top-500 source scan makes this concrete:

54 / 495 scanned public charts use Helm hooks.
42 / 54 hook charts look likely problematic for production lifecycle support.
6 / 54 need review.
6 / 54 look probably benign/test-only.

The risk estimate comes from stored hook details: phase, weight, delete policy, Jobs, CRDs, cluster RBAC, webhooks, APIServices, lookup, and generated-fact signals. The detailed strategy lives in Hook Lifecycle Strategy.

During import, the harness must not execute hooks. It should inventory hook templates and record:

hook phase
hook weight/order
hook object kind/name
hook delete policy
required RBAC / APIs / CRDs / Secrets / storage
expected side effect
safe-to-automate decision
required observation

Each hook then receives a disposition:

The proof claim must stay precise:

Render parity proves the selected non-hook object set.
Hook behavior is proven only by hook/lifecycle receipts and live observations.

So a production-ready chart with hooks needs at least a hook inventory, lifecycle policy, target-fact/preflight decision, execution-or-skip receipt, and observation receipt. A chart can still have a deterministic recipe and rendered object proof while its hook execution lane is blocked or not yet supported.

For GitOps delivery, safe hook-like behavior may be translated into Argo CD sync hooks or sync waves, but only when the semantics match and the translation gets its own lifecycle receipt. Unsafe or unclear procedural hooks remain blockers.

Recipe Or Variant?

Use this split:

Recipe-level:
  chart source
  dependency closure
  value schema and known value paths
  fact requirements
  allowed extension slots
  lifecycle policy
  forbidden or review-only mechanisms

Recipe/base variant-level:
  chosen values
  selected components
  target fact bindings
  capability profile
  generated fact bindings
  explicit overlays
  namespace and release name

Derived ConfigHub variant-level:
  target / environment / region / customer identity
  labels and annotations
  gates and approvals
  links
  placeholders and TransformPaths
  existing rendered field values
  observation policy

Normal Helm-rendered changes such as HA mode, TLS posture, cloud/provider settings, CRD posture, existing-Secret mode, or replica/topology modes that change chart branches or object shape become recipe/base variants. Approved post-render changes such as target, environment, region, replica count over an existing workload field, labels, gates, links, target facts, placeholders, TransformPaths, functions, checks, and already-rendered editable fields become derived ConfigHub variants or Day-2 operations. Create another recipe only when the chart source, chart version, umbrella composition, import strategy, or recipe semantics materially differ.

For product-tier boundaries, see Product Support Tiers For Helm Scenarios.

How Decisions Are Checked

A generated recipe is not trusted because the AI wrote it. It is trusted only when the proof chain passes.

The main checks are:

What this command does. cub installer is a released, open-source plugin for the cub CLI. cub installer setup pulls a catalog package and writes its Kubernetes files locally. It does not apply those files to a cluster; use kubectl, Argo CD, or Flux for delivery. The generated scripts stop before doing any work when the plugin or kustomize is missing.

source lock exists and has stable digest
dependency lock exists
recipe and variant artifacts exist
variant revision binds recipe/effective values/facts/capability/renderer/output
regular Helm render semantically matches cub installer setup output
allowed differences are classified
exact rendered objects are scanned
install gate records allow/warn/block decision
ConfigHub upload or OCI path records proof when used
live observation receipt records what reached a cluster

For Redis, an allowed difference is the installer Namespace support object. For the Redis default variant, the rendered Secret is classified as separated by cub installer; for reuse-existing-secret, the Secret becomes a target fact requirement instead of rendered secret material.

What The Harness Produces

For each promoted chart, expect these artifacts:

recipes/<repo>/<chart>/<version>/
  recipe.yaml
  source-lock.yaml
  dependency-lock.yaml
  helm-plan.yaml
  chart-dossier.yaml
  control-points.yaml
  value-model.yaml
  helm-pain-report.yaml
  variants/<variant>/variant.yaml
  revisions/<variant>/r001/
    variant-revision.yaml
    rendered/release-objects.yaml
    receipts/*

packages/<repo>/<chart>/<version>/
  installer.yaml
  bases/<variant>/*

Aggregate proof lives under data/ and runs/. The root CATALOG.md is the human entry point for choosing charts and variants.

Related Docs

• Public mission and quick start: README.md
• Short explanation: how-the-harness-works.md
• Customization placement algorithm: customization-algorithm.md
• Current pathway review snapshot: current-pathway-review.md
• Repo consistency review snapshot: repo-consistency-review.md
• Consolidated doctrine and historical execution record: agreed-execution-plan.md
• Artifact verifier specification: artifact-verifier-spec.md