# Lifecycle Route Actions

**UNOFFICIAL/EXPERIMENTAL.** Generated by
`scripts/generate-lifecycle-route-actions.mjs`. Do not hand-edit. Regenerate
with `npm run lifecycle:route-actions`.

This projects the legible lifecycle-route contract
([../lifecycle-routes/](../lifecycle-routes/summary.md)) into machine-readable
**action packets**: per route, the lifecycle phase, the action kind, required
target facts, an agent-readable input block, the evidence required to advance,
and an explicit `automatic` flag. It lets a UI or agent turn "where a
hook/lifecycle action should go" into a checkable preflight/action/observe plan
— without claiming live or automatic execution.

Schema: [schemas/lifecycle-route-action.schema.json](../../schemas/lifecycle-route-action.schema.json).
Forms: [actions.csv](./actions.csv), [actions.json](./actions.json) (agent
interface), field definitions in [contract.md](./contract.md).

## The honest flag

0 of 53 packets are `automatic`. No route is
executed by the product today, so `automatic` is `false` everywhere; a packet
is a *plan*, not a claim that anything ran. `automatic` only becomes `true`
when `execution_mode` is `product-executes` and committed evidence proves it.

## Distribution

| Disposition | Packets |
| --- | ---: |
| `observed` | 42 |
| `blocked` | 7 |
| `routed` | 2 |
| `not-run` | 1 |
| `per-target` | 1 |

| Lifecycle phase | Packets |
| --- | ---: |
| `pre-apply` | 17 |
| `observe` | 16 |
| `preflight` | 11 |
| `post-apply` | 8 |
| `pre-render` | 1 |

| Action kind | Packets |
| --- | ---: |
| `run-job` | 13 |
| `accept-target-policy` | 7 |
| `run-preflight` | 7 |
| `preserve-ordering` | 5 |
| `install-crd` | 4 |
| `observe-webhook` | 4 |
| `run-test` | 4 |
| `stage-target-facts` | 4 |
| `run-check` | 3 |
| `gitops-sync-hook` | 1 |
| `verify-render` | 1 |

## Named source drift

7 packet(s) carry a source-version drift, named (not hidden):

- `prometheus-community/kube-prometheus-stack`: route source version 85.3.0; catalog has 85.3.3, 86.1.0

## Not yet projected

These hook-like lifecycle behaviors are real but are not in the hook-disposition
source, so they are not projected here yet. They are illustrated in the user doc
([../../docs/user/chart-hooks-what-happens.md](../../docs/user/chart-hooks-what-happens.md)):

- **cert-manager / External Secrets** webhook + CRD lifecycle — observed in
  `data/lifecycle-observations/cert-manager-eso/` (CRD ownership per target,
  `startupapicheck` as a post-apply API dry-run), not a hook-disposition row.
- **Consul UI Ingress** — a per-target controller-health decision, not a
  hook-disposition row.

Folding those sources into this projection (so they get action packets too) is
the next primitive worth adding to the model.

## How To Read One Packet

`route_name` is the route; `lifecycle_phase` is when it happens (pre-render →
preflight → pre-apply → post-apply → observe, or refuse); `action_kind` is what
kind of step it is; `disposition` is one of `observed, routed, per-target, not-run, blocked, refused`;
`automatic` says whether the product runs it (always `false` today);
`required_target_facts` and `human_command` are the inputs; `agent_inputs`
(JSON) is the stable block an agent selects from; `evidence_required` is what
must exist before the row can advance to observed.

## Boundaries

- Static projection of committed data. No hook is executed, no cluster touched,
  no ConfigHub state changed, no `runs/` receipt edited.
- A packet is a plan, not a proof. `observed` packets point at the receipt in
  `evidence_or_next_action`; the rest name what is still required.