From ff2064d759926a8f113cd321d9e370b9f8614eb0 Mon Sep 17 00:00:00 2001 From: codex Date: Sun, 26 Jul 2026 02:20:00 +0200 Subject: [PATCH] Finish rail-kubernetes bootstrap handoff --- README.md | 4 +- SCOPE.md | 9 ++- WORK-RECORDS.md | 4 +- docs/README.md | 1 + docs/cluster-compatibility-handoff.md | 77 +++++++++++++++++++ docs/wave-1-contract.md | 13 +++- ...-K8S-WP-0001-bootstrap-and-wave1-import.md | 12 ++- 7 files changed, 108 insertions(+), 12 deletions(-) create mode 100644 docs/cluster-compatibility-handoff.md diff --git a/README.md b/README.md index f458148..c97d897 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,9 @@ the relevant `reef-*` repo. ## Current Status -This repo is in first-wave bootstrap. +First-wave bootstrap is complete. The repo now owns the generic Kubernetes rail +contract, tooling, and migration-window compatibility handoff from +`railiance-cluster`. The boundary and source material come from: diff --git a/SCOPE.md b/SCOPE.md index 89f87ec..08d4ff0 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -61,10 +61,11 @@ the S2 ownership repo. ## Current State -- Status: active bootstrap -- Implementation: baseline repo, declaration, and first repo-local workplan are present -- Stability: evolving -- Usage: wave-1 home for the default Kubernetes rail +- Status: first-wave bootstrap complete +- Implementation: declaration, generic lifecycle docs/tooling, and the cluster + compatibility handoff are present +- Stability: early but usable +- Usage: canonical wave-1 home for the default Kubernetes rail --- diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index 7ca5436..2c4657b 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -8,8 +8,8 @@ | Kind | ID | Status | Lane | Source | | --- | --- | --- | --- | --- | -| workplan | RAIL-K8S-WP-0001 | active | — | workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md | +| workplan | RAIL-K8S-WP-0001 | finished | — | workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md | | task | RAIL-K8S-WP-0001-T01 | done | — | workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md | | task | RAIL-K8S-WP-0001-T02 | done | — | workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md | -| task | RAIL-K8S-WP-0001-T03 | wait | — | workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md | +| task | RAIL-K8S-WP-0001-T03 | done | — | workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md | | task | RAIL-K8S-WP-0001-T04 | done | — | workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md | diff --git a/docs/README.md b/docs/README.md index ff0822c..0fbe462 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,5 +8,6 @@ - `promote-rollback-onboarding.md` — representative lifecycle command path - `railiance-run-command.md` — stage 1 command behavior contract - `create-overlay-command.md` — overlay scaffolder behavior contract +- `cluster-compatibility-handoff.md` — migration-window handoff from `railiance-cluster` - `wave-1-contract.md` — current rail contract and boundary summary - `source-import-plan.md` — source material and migration direction from existing repos diff --git a/docs/cluster-compatibility-handoff.md b/docs/cluster-compatibility-handoff.md new file mode 100644 index 0000000..d2cf1aa --- /dev/null +++ b/docs/cluster-compatibility-handoff.md @@ -0,0 +1,77 @@ +# Cluster Compatibility Handoff + +## Purpose + +Define the migration-window handoff between `railiance-cluster` and +`rail-kubernetes` for the generic workload lifecycle surface. + +Wave 1 makes `rail-kubernetes` the durable owner of the generic Kubernetes +rail contract. `railiance-cluster` remains the S2 substrate owner and keeps a +thin compatibility shim so current operators do not need a flag day. + +## Canonical Command Owner + +Use `rail-kubernetes/bin/railiance` as the canonical entrypoint for these +generic rail commands: + +- `create-overlay` +- `run` +- `deploy` +- `observe` +- `promote` +- `rollback` + +New behavior, docs, and fixes for those commands should land in +`rail-kubernetes` first. + +## Cluster-Side Compatibility Shim + +During the migration window, `railiance-cluster/bin/railiance` keeps the same +six command names but resolves them in this order: + +1. If `RAILIANCE_RAIL_KUBERNETES_BIN` is set, use that executable path. +2. Else, if a sibling checkout exists at `../rail-kubernetes/bin/railiance`, + delegate to it. +3. Else, fall back to the temporary compatibility copies still present in + `railiance-cluster`. + +If `RAILIANCE_RAIL_KUBERNETES_BIN` is set but not executable, the cluster-side +shim fails closed rather than silently using a different path. + +This keeps existing `railiance-cluster/bin/railiance ...` invocations working +while shifting canonical ownership to `rail-kubernetes`. + +## What Still Stays Outside The Handoff + +The compatibility shim does not expand the rail boundary. + +Still retained in `railiance-cluster` as S2 substrate operations: + +- `backup` +- `preflight` + +Still present in `railiance-cluster` but outside the `rail-kubernetes` handoff: + +- shared bootstrap helpers such as `doctor`, `plan-host`, `cloudinit`, + `init-repo`, `build-spore`, `seed-local`, and `checklist` +- workload-specific helpers such as `deploy-triage-robustness` and + `admin-sync-smoke` + +Those commands need their own long-term placement review; they are not part of +the generic rail contract. + +## Operator Migration Path + +Operators can move without changing command arguments: + +1. Clone `rail-kubernetes` alongside `railiance-cluster`, or set + `RAILIANCE_RAIL_KUBERNETES_BIN` to the preferred checkout. +2. Continue using `railiance-cluster/bin/railiance` during the migration window + if needed; it will delegate when the rail repo is available. +3. Prefer `rail-kubernetes/docs/` as the canonical documentation surface for + the six generic lifecycle commands. + +## Exit Condition + +The migration window can end once current operator entrypoints and automation +no longer depend on the cluster-side fallback copies. diff --git a/docs/wave-1-contract.md b/docs/wave-1-contract.md index f7fd29e..7c60cc7 100644 --- a/docs/wave-1-contract.md +++ b/docs/wave-1-contract.md @@ -54,6 +54,13 @@ Wave 1 `rail-kubernetes` must not assume: Until the extraction is complete, `railiance-cluster` remains the compatibility surface for current operators. -`rail-kubernetes` should become the durable home of the contract first. Only -then should commands, docs, schemas, and helpers move here in a migration-safe -sequence. +The current migration-window handoff is: + +- `rail-kubernetes/bin/railiance` is the canonical owner for the six generic + lifecycle commands; +- `railiance-cluster/bin/railiance` keeps those command names as a thin + delegation shim with a temporary local fallback; +- retained S2 operations and non-rail helper debt stay outside this handoff. + +See `docs/cluster-compatibility-handoff.md` for the command-resolution path and +operator migration steps. diff --git a/workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md b/workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md index c0147da..afc37c1 100644 --- a/workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md +++ b/workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md @@ -4,7 +4,7 @@ type: workplan title: "Bootstrap rail-kubernetes and import the wave-1 contract" domain: financials repo: rail-kubernetes -status: active +status: finished owner: codex topic_slug: railiance created: "2026-07-25" @@ -99,7 +99,7 @@ verified the imported surface with `bash -n`, `python3 -m py_compile`, and ```task id: RAIL-K8S-WP-0001-T03 -status: wait +status: done priority: medium state_hub_task_id: "18140d90-d10e-47fe-b7da-d454550466b1" ``` @@ -113,6 +113,14 @@ Acceptance: - current operators do not need a flag day - the retained S2 surface stays narrow and temporary +2026-07-26: Added `docs/cluster-compatibility-handoff.md` as the canonical +handoff contract for the migration window. On the cluster side, +`railiance-cluster/bin/railiance` now delegates `create-overlay`, `run`, +`deploy`, `observe`, `promote`, and `rollback` to `rail-kubernetes` when a +configured or sibling checkout exists, with a temporary local fallback when it +does not. This keeps current operator entrypoints working without expanding the +rail boundary. + ## T04 - Register `rail-kubernetes` in State Hub and Fabric ```task