Lifecycle Route Contract · Config Workshop

Generated at: 2026-07-30T12:38:02.000Z UTC · source: committed helm-expt evidence for this rendered repository document.

UNOFFICIAL/EXPERIMENTAL. Schema and derivation rules for routes.csv and routes.json, generated by scripts/generate-lifecycle-routes.mjs. Both the data and this contract are generated from the same constants, so they cannot drift.

Purpose

For every hook or hook-like lifecycle behavior, make machine-readable: the route, who executes it, the default, the named alternatives and their requirements, whether a human and an agent can pick an alternative, the evidence or next action, and whether it is safe to show as automatic.

Columns

Column	Meaning
`chart` / `version`	Source chart and version.
`base_or_variant`	Specific base when a selected receipt proves an exact route; empty means the chart-level route used by bases without an exact receipt.
`quirk_class`	The behavior class, derived from `route_name` (see table).
`hook_phases`	Helm hook phases recorded by the source scan.
`source_disposition`	The raw disposition word from the source data, kept for traceability.
`disposition`	Published word: `observed`, `routed`, `per-target`, `refused`, or `todo`.
`route_name`	The selected/current route for this behavior.
`default_route`	The default route among the alternatives (equals `route_name`).
`alternatives`	Named off-ramp routes for this quirk class.
`route_requirements`	What the current route needs (target facts, render conditions).
`execution_mode`	Who performs it: `product-executes`, `user-executes`, `target-owned`, or `not-yet-executable`.
`human_offramp`	How a human picks an alternative (`recipe-base-or-values` or `none`).
`agent_offramp`	How an agent picks an alternative (`routes-json` or `none`).
`live_status`	`observed`, `blocked`, `none`, or `candidate-route-plan`.
`safe_as_automatic`	`yes` only when `execution_mode` is `product-executes` and evidence proves it.
`evidence_or_next_action`	Receipt path when observed, otherwise the next action.

Invariants

No silent automation. safe_as_automatic = yes requires execution_mode = product-executes plus evidence. No row qualifies today, so the column is uniformly no. This is deliberate.
routed names an executor. A routed row always records an execution_mode; candidate-route/recipe-needed only map to a real disposition once a route and executor are named.
refused is final; todo is unfinished. refused is a deliberate decision not to run a behavior automatically. todo (from recipe-needed/candidate-route-plan) means no recipe/route exists yet and a next action is named. They are never merged.
Generated, not authored. Regenerate with npm run lifecycle:routes; verify byte-for-byte with npm run lifecycle:routes:verify.

Source Disposition Mapping

The source data uses more than one vocabulary. This is the published join.

Source value	Published disposition
`observed`	`observed`
`routed`	`routed`
`per-target`	`per-target`
`refused`	`refused`
`recipe-needed`	`todo`
`candidate-route`	`routed`
`candidate-route-plan`	`todo`
`selected-route-receipt`	`observed`

Route → Quirk Class

route_name	quirk_class
`preflight-or-presync`	`hook-phase`
`preflight-or-presync-crd-apply`	`crd-install`
`postsync-check-or-observation`	`hook-phase`
`upgrade-action-with-receipt`	`hook-phase`
`explicit-managed-action`	`hook-phase`
`argocd-or-flux-lifecycle-hook`	`hook-phase`
`target-class-preflight-and-upgrade-action`	`per-target-hook`
`recipe-time-lifecycle-verification`	`hook-phase`
`explicit-test-check`	`hook-test`
`webhook-readiness-observation`	`webhook-readiness`
`target-facts-or-preflight`	`target-facts`
`preserve-ordering`	`hook-weight-ordering`
`preserve-cleanup-policy`	`hook-delete-policy`
`delete-cleanup-policy`	`hook-delete-policy`
`explicit-delete-cleanup-action`	`hook-delete-policy`
`explicit-post-install-check`	`hook-test`
`postsync-readiness-observation`	`webhook-readiness`
`self-contained-crd-base`	`crd-install`

Route → Execution Mode (base)

Before the todo/refused override, which forces not-yet-executable. No route maps to product-executes.

route_name	execution_mode
`preflight-or-presync`	`user-executes`
`preflight-or-presync-crd-apply`	`user-executes`
`postsync-check-or-observation`	`user-executes`
`upgrade-action-with-receipt`	`user-executes`
`explicit-managed-action`	`not-yet-executable`
`argocd-or-flux-lifecycle-hook`	`target-owned`
`target-class-preflight-and-upgrade-action`	`user-executes`
`recipe-time-lifecycle-verification`	`user-executes`
`explicit-test-check`	`user-executes`
`webhook-readiness-observation`	`target-owned`
`target-facts-or-preflight`	`user-executes`
`preserve-ordering`	`target-owned`
`preserve-cleanup-policy`	`target-owned`
`delete-cleanup-policy`	`target-owned`
`explicit-delete-cleanup-action`	`user-executes`
`explicit-post-install-check`	`user-executes`
`postsync-readiness-observation`	`user-executes`
`self-contained-crd-base`	`target-owned`

Quirk Class → Alternatives (off-ramps)

The off-ramp routes a user or agent can choose instead of the default, and what each needs. Grounded in ../../docs/user/hook-lifecycle-strategy.md and ../../docs/planning/where-does-my-hook-go.md.

quirk_class	alternative route	requirement
`hook-phase`	`argocd-or-flux-lifecycle-hook`	a GitOps controller (Argo CD/Flux) that runs sync hooks or sync waves
`hook-phase`	`target-facts-or-preflight`	the prerequisite supplied as a target fact or preflight before apply
`hook-phase`	`refuse`	accept that the catalog will not run this automatically and do it manually
`crd-install`	`self-contained-crd-base`	a preset config that renders the required CRDs as ordinary objects before the workloads
`crd-install`	`target-owned-crds`	the cluster or an operator owns CRD install and upgrade out of band
`crd-install`	`refuse`	use a no-crds base and install/upgrade the CRDs yourself
`hook-delete-policy`	`delete-on-uninstall`	accept deletion of the hook-managed object on uninstall
`hook-delete-policy`	`refuse`	manage cleanup manually and keep the object
`hook-weight-ordering`	`argocd-sync-waves`	a GitOps controller that maps hook weights to sync waves
`hook-weight-ordering`	`apply-order`	an apply step that preserves the documented order
`hook-test`	`ci-check`	run the test as a CI or post-apply check instead of a Helm test hook
`hook-test`	`skip-test`	accept that the test is not run automatically
`webhook-readiness`	`postsync-check-or-observation`	a post-apply readiness check you run or observe
`target-facts`	`preflight-or-presync`	a preflight step that establishes the fact before apply
`target-facts`	`refuse`	supply the fact manually and accept no preflight
`per-target-hook`	`per-target-scope-split`	named target classes, each with its own route decision

Off-ramps Today

The human off-ramp is recipe base/values selection. The agent off-ramp is routes.json: a stable enumeration of routes, defaults, alternatives, and requirements an agent can read and act on. Selecting an alternative is a recipe-level change today; this contract makes the choice legible to both readers. Neither off-ramp implies the product executes the route - see invariant 1.