Large Machine Roadmap

Updated: 2026-06-05

This roadmap is for the large machine that can run live Kubernetes and GitOps tests. It is outcome-driven: each task is done only when committed receipts and verifiers prove the claimed outcome.

For the current project-wide roadmap, use Roadmap. This file is the live-evidence lane plan and remains useful for cluster-heavy work, but it is not the canonical roadmap index.

North Star

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

For derived ConfigHub variants:

Every advertised post-render operating choice has clone/link/check/gate
evidence, and delivery claims have target-bound live receipts.

Non-Negotiable Truth Rules

1. Do not say "all charts" unless every chart-recipe-variant row in the lane matrix has the relevant PASS receipt.
2. Do not say "live" unless there is an actual cluster/controller observation receipt.
3. Do not say "derived variants are proven" unless the statement names whether they are intended-state only or target-bound live.
4. Do not say "quirks checked" unless the receipt checks the specific quirks for that chart: CRDs, hooks, webhooks, RBAC, generated Secrets, target facts, PVCs, lookups, ingress/TLS, images, storage, and day-2 behavior.
5. A verifier passing means "the committed evidence is self-consistent." It does not automatically mean "fresh live run succeeded today."

Roadmap Overview

Phase 0 - Truth Controls

Outcome: the repo stops rewarding vague verification claims.

Tasks:

• Add or update a user-facing "Verification Lanes" page that explains every major npm run verifier in plain English.
• Add a top-level "Current Proof Status" page that pulls from the lane matrix and says what is pass, missing, and backlog.
• Extend the lane matrix if needed so derived intended-state and target-bound derived live receipts are separate lanes.
• Add a "blocked receipt" pattern for live attempts that fail due to cluster, target, controller, chart, or ConfigHub behavior.
• Require every future handover to include exact lane counts from data/outcome-coverage/summary.md.

Done when:

• npm run docs:verify, npm run lane-tests:verify, and the new or updated verifier fail if status claims drift from evidence.

Phase 1 - Live Parity Canaries

Outcome: one simple and one stateful chart prove live Helm-vs-ConfigHub parity.

Recommended canaries:

For each canary, run and receipt:

• fresh helm install into kind or equivalent;
• ConfigHub kubectl/apply delivery;
• ConfigHub OCI plus Argo delivery;
• semantic object comparison;
• runtime health and meaningful workload observation;
• cleanup or retained-resource summary.

Done when:

• confighub_oci_argo_live and live_helm_vs_confighub_dual_compare are PASS for the exact canary rows.
• The lane matrix and docs explain only those rows as pass.

Phase 2 - Target-Bound Derived Variants

Outcome: derived variants become operational, not only intended-state clones.

Start with:

Tasks:

• Create or select real targets for the current ConfigHub context.
• Attach targets to selected derived variants.
• Apply with gates/checks as appropriate.
• Record live apply, runtime observation, and cleanup receipts.
• Decide whether production gates should block apply until explicitly approved and receipt that behavior.

Done when:

• npm run derived-variants:verify covers intended-state receipts.
• npm run derived-variants:target-bound:verify covers target-bound live receipts.
• npm run derived-variants:target-bound:summary:verify keeps Target-Bound Derived Variants current for human review.
• The docs say which derived variants are target-bound live and which are not.

Phase 3 - Top-20 Row-Level Live Coverage

Outcome: top-20 chart support is exact by main choice, not fuzzy by chart.

Tasks:

• Work from data/lane-test-matrix/variant-lanes.csv.
• Prioritize missing non-default main choices for top-20 charts: existing-secret, no-crds, server-only, ingress, HA, storage, and ClusterIP.
• For each row, run local kind apply and ConfigHub proof if missing.
• Then run OCI/Argo and live parity lanes in batches.
• Commit receipts by row, not by chart-level headline.

Done when:

• Every top-20 declared main choice has PASS in:
  • helm_template_vs_installer_setup
  • confighub_upload_variant_scan_safe_ops
  • local_kind_kubectl_apply
• At least the first wave has PASS in:
  • confighub_oci_argo_live
  • live_helm_vs_confighub_dual_compare

Phase 4 - Chart Quirk Coverage

Outcome: a human can see whether a chart's hard parts have actually been tested.

Tasks:

• Generate per-chart quirk profiles from recipe metadata, chart facts, and receipts.
• Add receipt checks for:
  • CRD install/no-CRD choices;
  • hook lifecycle and cleanup;
  • admission webhooks;
  • generated and existing Secrets;
  • target facts;
  • PVC/stateful behavior;
  • service/ingress/TLS behavior;
  • mutable image tags and digest overrides;
  • upgrade and rollback for stateful or hook-heavy charts.
• Make untested quirks visible as missing, not hidden in prose.

Done when:

• Per-chart pages include a "Quirks checked" and "Quirks not yet checked" section generated or verified from evidence.

Phase 5 - What Am I Getting?

Outcome: a new human can understand the value without reading the whole proof corpus.

The current user-facing entry point is:

docs/user/what-you-get.md

It answers:

• What does ConfigHub add beyond helm install?
• Which charts are currently supported and at what proof level?
• What is a base variant versus a derived ConfigHub variant?
• Which workflows are ready now: render review, ConfigHub upload, derived environment/customer variants, local apply, GitOps?
• Which workflows are still backlog: full live parity, target-bound derived variants, production support, release/OCI handoff?

Per-chart cards should include:

Next improvements:

• keep README.md and docs/user/README.md pointing to this page before deep proof mechanics;
• add per-chart status cards to CATALOG.md or the static site;
• keep the page tied to generated evidence rather than hand-copied counts.

Phase 6 - Docs Organization

Outcome: docs are findable by audience and stale files cannot confuse users.

Proposed folder rules:

Tasks:

• Keep docs/user/ limited to first-run and workflow docs.
• Keep stable doctrine in docs/reference/.
• Keep active roadmaps and issue mirrors in docs/planning/.
• Move historical snapshots to docs/planning/archive/.
• Update docs/README.md whenever a manual doc moves.
• Run npm run docs:verify.

Done when:

• A new user can start at README.md and follow a serial path:
  1. what this is;
  2. what they get;
  3. choose a chart;
  4. run a tutorial;
  5. inspect proof status;
  6. understand limitations.

Highest Value Next 20 Tasks

1. Add a user-facing verification-lanes page.
2. Add a current proof status page generated or verified from the lane matrix.
3. Keep the NGINX live Helm-vs-ConfigHub parity canary green.
4. Keep the Redis live Helm-vs-ConfigHub parity canary green.
5. Keep the target-bound live receipt schema for derived variants green.
6. Keep the NGINX-prod-us-east target-bound live receipt green.
7. Implement the namespace mutation and Redis Secret/fact handling needed for Redis-staging-eu-west.
8. Pick the next target-bound derived variant after Redis's mutation/secret blocker is resolved.
9. Fix or explain Grafana placeholder drift (#156).
10. Add per-chart "what am I getting?" cards for the top-20.
11. Add per-chart "quirks checked / missing" sections.
12. Move non-user-facing files out of docs/user/.
13. Add a docs inventory table by audience and purpose.
14. Expand ConfigHub proof row coverage for top-20 non-default main choices.
15. Expand local-kind row coverage for top-20 non-default main choices.
16. Expand OCI/Argo live receipts beyond the first NGINX row in the lane matrix.
17. Add first live dual-compare receipt to the lane matrix.
18. Add blocked-receipt handling for live harness failures.
19. Update README.md to lead with value and current proof status.
20. Update static site or CATALOG.md so chart status is easy to inspect.

Suggested First Commit On Large Machine

Do not start with all charts. Start with one canary and the receipt/verifier shape:

NGINX http-clusterip:
  live Helm install
  ConfigHub kubectl/apply
  ConfigHub OCI/Argo
  semantic comparison
  runtime observation
  cleanup
  lane matrix update

Once that pattern is correct and honest, repeat it for the next selected top-20 row.