---
id: RAIL-K8S-WP-0001
type: workplan
title: "Bootstrap rail-kubernetes and import the wave-1 contract"
domain: financials
repo: rail-kubernetes
status: active
owner: codex
topic_slug: railiance
created: "2026-07-25"
updated: "2026-07-26"
state_hub_workstream_id: "1f2254f5-a873-46fc-a77c-bc725eeaaeb8"
---

# RAIL-K8S-WP-0001 - Bootstrap rail-kubernetes and import the wave-1 contract

## Goal

Turn `rail-kubernetes` into the concrete home of the default Railiance
execution rail.

## Boundaries

This workplan may bootstrap the repo, publish the initial declaration, and
import the generic wave-1 contract.

It must not:

- absorb S2 substrate ownership from `railiance-cluster`
- normalize workload-specific helper commands into the rail
- pretend the migration is complete before compatibility shims exist

## T01 - Establish the repo baseline and rail declaration

```task
id: RAIL-K8S-WP-0001-T01
status: done
priority: high
state_hub_task_id: "9bab36db-e094-4e41-af76-b6bf5e73be78"
```

Create the baseline repo files, the initial rail declaration, and the first
wave-1 contract summary.

Acceptance:

- baseline repo files exist
- `declarations/rail.yaml` exists
- the repo states its boundary with `railiance-cluster`

2026-07-25: Created the initial repo baseline, declaration, and wave-1
contract summary.

## T02 - Import the reviewed generic contract material

```task
id: RAIL-K8S-WP-0001-T02
status: done
priority: high
state_hub_task_id: "148276a2-2e40-4d56-89dd-2930c5e4309c"
```

Bring the reviewed generic lifecycle docs, schema, examples, and helper
surfaces into this repo in a migration-safe sequence.

Acceptance:

- the import sequence is anchored in the reviewed extraction map
- imported material stays generic to the Kubernetes rail
- the repo becomes a real home for the default rail rather than only a shell

2026-07-25: Established the repo-local contract summary and explicit source
import plan. Full import of docs, schema, examples, and helper surfaces is
still pending.

2026-07-25: Imported the first core generic contract artifacts from
`railiance-cluster`: `docs/deployment-lifecycle.md`,
`docs/app-toml-contract.md`, `schemas/railiance-app.schema.json`, and
`examples/railiance/app.toml`. Helper command surfaces and the remaining
supporting docs are still pending.

2026-07-25: Imported the remaining generic supporting docs from
`railiance-cluster`: `docs/overlay-repo-pattern.md`,
`docs/canary-helm-template.md`, `docs/stage2-deploy-observe.md`,
`docs/promote-rollback-onboarding.md`, and
`docs/railiance-run-command.md`. Helper scripts and command implementations
remain pending.

2026-07-26: Imported the remaining reviewed helper surfaces from
`railiance-cluster`: `tools/create_railiance_overlay_repo.sh`,
`tools/cmd/railiance-run`, `tools/cmd/railiance-stage2`, and
`tools/cmd/railiance-stage3`. Added a rail-local `bin/railiance` dispatcher
limited to `create-overlay`, `run`, `deploy`, `observe`, `promote`, and
`rollback`, documented `create-overlay`, refreshed the source import plan, and
verified the imported surface with `bash -n`, `python3 -m py_compile`, and
`bin/railiance help`.

## T03 - Prepare the compatibility handoff from `railiance-cluster`

```task
id: RAIL-K8S-WP-0001-T03
status: wait
priority: medium
state_hub_task_id: "18140d90-d10e-47fe-b7da-d454550466b1"
```

Define the thin compatibility path that keeps current operators functional
while the extraction proceeds.

Acceptance:

- the compatibility path is explicit
- current operators do not need a flag day
- the retained S2 surface stays narrow and temporary

## T04 - Register `rail-kubernetes` in State Hub and Fabric

```task
id: RAIL-K8S-WP-0001-T04
status: done
priority: medium
state_hub_task_id: "d78b5712-f305-4967-9034-9b9471633755"
```

Register the repo from classification and add it to the Fabric repository
registry with rail-family metadata.

Acceptance:

- State Hub recognizes the repo and its workplan
- Fabric recognizes the repo as `repo_family: rail`
- ownership and primary contract metadata are visible

2026-07-25: Registered `rail-kubernetes` in State Hub and generated
`WORK-RECORDS.md` plus `.custodian-brief.md`. Added `rail-kubernetes` to
`railiance-fabric/registry/railiance-repos.yaml` as `repo_family: rail` with
`ownership_repo: railiance-cluster`. The local repo history is now reconciled
with the remote bootstrap commit and pushed to
`forgejo-remote:coulomb/rail-kubernetes.git`. A targeted live Fabric registry
sync initially failed because `http://127.0.0.1:8765` was down, but after
starting the local registry service the targeted sync succeeded. Fabric now
stores `rail-kubernetes` as a live registered repo with snapshot `id: 96` at
commit `4c2b76e3ecc082bc310523bdcd6c660716e4248b`.