Date: 2026-07-25 Status: Accepted

## Context

Railiance wants `rail-*` repos to represent workload execution contracts rather than abstract naming ideas.

Today, the concrete Kubernetes workload contract already exists, but it is embedded in `railiance-cluster`. That repo currently owns both:

- the S2 Kubernetes substrate
- and the generic workload lifecycle and tooling that run on top of it

That mixed ownership is the main blocker to introducing the first real rail.

## Decision

Railiance will treat `rail-kubernetes` as the wave-1 base rail.

The boundary is:

- `railiance-cluster` owns the Kubernetes substrate and its prerequisites
- `rail-kubernetes` owns the generic workload-on-Kubernetes execution contract

Workload-specific helper flows currently living in `railiance-cluster` are temporary exceptions and must be rehomed rather than carried forward as part of the generic rail.

## Consequences

### Positive

- The first real rail gains a concrete ownership boundary.
- `railiance-cluster` can return to a clean S2 substrate identity.
- Future rails such as `rail-knative` get a stable base boundary to extend from.
- `rapp-*` repos gain a clearer execution-contract home for Kubernetes-managed workloads.

### Required Follow-On Work

- Create the detailed `rail-kubernetes` boundary contract and migration map.
- Split generic lifecycle docs, schema, examples, and Stage 1-3 tooling out of `railiance-cluster`.
- Leave a compatibility path so current users of the cluster repo are not broken during the migration.
- Rehome workload-specific helpers that do not belong in either boundary.

### Constraints

- `rail-kubernetes` must not take ownership of cluster bootstrap, operators, or kubeconfig management.
- `railiance-cluster` must not continue as the owner of generic workload promotion semantics after the split.
- `rail-knative` should follow this cleanup, not bypass it.

## Notes

This ADR does not require all current files to move immediately.

It requires the ownership line to be explicit now, so practical repo separation can proceed without ambiguity.