Add examples/ctrlplane: read-only Ctrlplane System → ConfigHub plan mapper

[monadic]

What

A new top-level example, examples/ctrlplane, that maps a Ctrlplane System bundle onto a proposed ConfigHub governed-app plan — read-only.

Ctrlplane is a release-orchestration layer (decides when/where a release goes and what gates it passes, then dispatches to a Job Agent). It explicitly does not store config or apply manifests. This example reads a Ctrlplane declarative bundle and proposes the equivalent ConfigHub app using the variant model:

Ctrlplane	→ ConfigHub
System	app (naming root)
Deployment	base Unit (upstream, in <app>-base)
Environment	Space + downstream Unit variant (--upstream-unit)
Resource	Target
JobAgent	delivery strategy (argocd → confighub-oci-argo)
Policy	approval gate / verification note
(promotion)	cub unit update <variant> --upgrade

The Deployment becomes a base/upstream Unit; each Environment is a downstream variant linked to it. Promotion is a governed --upgrade (pull from upstream) — the ConfigHub-native parallel to Ctrlplane promoting a Version across environments. This preserves the promotion relationship that independent per-environment units would throw away.

What it proves

You can turn a Ctrlplane "app" definition into a ConfigHub governed app — base + per-environment variants, targets, delivery strategy, approval gates — without touching ConfigHub or a cluster. It also surfaces the real seams where the two models diverge.

Read-only by default

• ./setup.sh --explain — human-readable plan
• ./setup.sh --explain-json | jq — machine-readable View Packet ("mutates": false)
• ./setup.sh --cub-commands — the reviewable cub commands (base unit, --upstream-unit variants, --upgrade promotion)
• ./setup.sh --apply — gated; refuses to auto-create, prints plan + asks you to review/run by hand

Sample bundle (systems/ecommerce-system.yaml) yields 3 spaces (1 base + staging + production), 3 units (1 base + 2 upstream-linked variants), 3 targets (= Deployment×Env×Resource), confighub-oci-argo strategy, and the production approval gate.

Honest seams (printed by the mapper)

1. Supply the rendered manifest once on the base Unit; variants inherit it via the upstream link and carry only env-local overrides (a Ctrlplane Deployment carries only an image reference).
2. Promotion = cub unit update <variant> --upgrade — diff afterward; --upgrade can silently under-propagate list/nested fields when leaf vs base list shapes differ.
3. Ctrlplane verification (Datadog/Prometheus/HTTP) has no ConfigHub-core equivalent; wire as a post-apply external check feeding the promotion gate.
4. Environment progression / gradual-rollout timing stays in Ctrlplane; ConfigHub governs and proves each step.

Status

The mapping (--explain, --explain-json, --cub-commands) is implemented and verified. The live create/apply path is not yet proven end-to-end against a ConfigHub space — that is the next step.

Verification

• cd ctrlplane && ./verify.sh → All checks passed.
• ./scripts/verify.sh → PASS: ctrlplane / All example checks passed.

Conforms to EXAMPLE_CONTRACT_STANDARD.md (README + AI_START_HERE + contracts.md + setup.sh --explain/--explain-json + verify.sh), registered in scripts/verify.sh, and listed in the top-level README.

Prereqs: python3 + PyYAML, jq.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.