---
id: RAIL-BS-WP-0012
type: workplan
title: "rail-kubernetes extraction from railiance-cluster"
domain: financials
repo: railiance-cluster
status: finished
owner: codex
topic_slug: railiance
created: "2026-07-25"
updated: "2026-07-26"
state_hub_workstream_id: "2b01ce91-35be-4947-832b-2f462c6ba472"
---

# RAIL-BS-WP-0012 - rail-kubernetes extraction from railiance-cluster

## Goal

Prepare the S2 side of the `rail-kubernetes` split so `railiance-cluster` can
return to a clean Kubernetes substrate identity while the generic
workload-on-Kubernetes contract moves to a future `rail-kubernetes` repo.

This workplan follows the boundary defined in
`/home/worsch/railiance-master/docs/rail-kubernetes-boundary.md`.

## Boundaries

This workplan may:

- clarify cluster-owned scope and retained files
- prepare compatibility notes and substrate-profile outputs
- identify exact move candidates and compatibility shims

It must not:

- silently move files into a new repo that does not exist yet
- break current `bin/railiance` users during the migration window
- reassert S2 ownership over generic workload lifecycle semantics once the
  boundary is clear

## T01 - Align `railiance-cluster` scope with the wave-1 boundary

```task
id: RAIL-BS-WP-0012-T01
status: done
priority: high
state_hub_task_id: "7255ef32-3fdf-473f-a5c0-62b509ee7a4e"
```

Update S2 scope and related docs so they clearly distinguish:

- Kubernetes substrate ownership that stays in `railiance-cluster`
- generic workload lifecycle ownership that belongs to `rail-kubernetes`

Done when the repo no longer describes the staged workload lifecycle as a
long-term S2 ownership concern.

2026-07-25: Updated `SCOPE.md`, `README.md`, and `docs/README.md` so S2 now
claims Kubernetes substrate ownership only, while the generic workload
lifecycle is marked as transitional material targeted for future
`rail-kubernetes`.

## T02 - Inventory exact extraction candidates and retained files

```task
id: RAIL-BS-WP-0012-T02
status: done
priority: high
state_hub_task_id: "e80b511a-33c6-445b-95e2-3d0755ea9b5e"
```

Inventory the current lifecycle docs, schema, examples, CLI commands, and
scaffolding assets that should move to `rail-kubernetes`, and record which
files remain cluster-owned.

Done when the repo has one reviewed move map tied to real file paths.

2026-07-25: Added `docs/rail-kubernetes-extraction-map.md` with reviewed file
paths for material that moves to `rail-kubernetes`, material that remains
cluster-owned, and migration debt that must be rehomed elsewhere.

## T03 - Define the cluster substrate profile consumed by `rail-kubernetes`

```task
id: RAIL-BS-WP-0012-T03
status: done
priority: high
state_hub_task_id: "517e2849-9b36-4508-9e2a-90f219e211c7"
```

Define the minimum cluster profile that S2 publishes for the future rail:

- ingress class and routing modes
- supported canary capabilities
- certificate path
- storage constraints
- operator/runtime prerequisites
- namespace and RBAC expectations

Done when `rail-kubernetes` has a narrow substrate contract to depend on.

2026-07-25: Added `docs/rail-kubernetes-substrate-profile.md` to publish the
current S2 substrate facts, guaranteed canary mode, operator/runtime
expectations, and explicit non-guarantees for wave 1.

## T04 - Prepare compatibility shims for the migration window

```task
id: RAIL-BS-WP-0012-T04
status: done
priority: medium
state_hub_task_id: "fdc9fa63-bee2-4774-b92f-63cf7a315603"
```

Blocked on T01-T03 and the creation of the future `rail-kubernetes` repo.

Plan the thin compatibility path that keeps current operators functional during
the split, including any temporary `bin/railiance` delegation or short pointer
docs left behind in `railiance-cluster`.

Done when the migration can proceed without a flag day for current users.

2026-07-26: Added `docs/rail-kubernetes-compatibility-shim.md` and updated the
cluster dispatcher so `create-overlay`, `run`, `deploy`, `observe`, `promote`,
and `rollback` delegate to `rail-kubernetes/bin/railiance` when a configured
or sibling checkout exists. The cluster repo keeps a temporary local fallback
for those six commands, while retained S2 commands and unrelated helper debt
stay outside the handoff.

## Notes

This workplan is intentionally repo-local. The framework-level separation plan
lives in `railiance-master/workplans/RMASTER-WP-0017-rail-rapp-reef-repo-separation.md`.