Add rail-kubernetes compatibility shim

README.md

@@ -7,20 +7,23 @@ cluster facts that downstream workload rails depend on.
 
 This repo is the Kubernetes substrate owner, not the long-term home for the
 generic workload-on-Kubernetes contract. The staged workload lifecycle,
-`railiance/app.toml`, and overlay/wrapper scaffolding still live here as a
+`railiance/app.toml`, and overlay/wrapper scaffolding now belong canonically to
-compatibility layer and are being prepared for extraction to a future
+`rail-kubernetes`; this repo keeps only a migration-window compatibility shim
-`rail-kubernetes` repo.
+and temporary compatibility copies while the split completes.
 
 ## Current Boundary
 
 - S2-owned here: k3s bootstrap, Helm and kubeconfig access, cluster-level
   backup/preflight, smoke checks, and published substrate expectations.
-- Transitional here only: generic Stage 1/2/3 workload lifecycle semantics,
+- Transitional here only: the compatibility shim and temporary copies for the
-  `railiance/app.toml`, canary/promotion CLI commands, and overlay scaffolding.
+  generic Stage 1/2/3 workload lifecycle, `railiance/app.toml`, canary and
+  promotion CLI commands, and overlay scaffolding.
 - Reviewed move map:
   [docs/rail-kubernetes-extraction-map.md](docs/rail-kubernetes-extraction-map.md)
 - Published substrate profile:
   [docs/rail-kubernetes-substrate-profile.md](docs/rail-kubernetes-substrate-profile.md)
+- Compatibility shim:
+  [docs/rail-kubernetes-compatibility-shim.md](docs/rail-kubernetes-compatibility-shim.md)
 
 ## Quick Start
 

WORK-RECORDS.md

@@ -13,7 +13,7 @@
 | workplan | RAIL-BS-WP-0009 | finished | — | workplans/RAIL-BS-WP-0009-activity-core-admin-sync-smoke.md |
 | workplan | RAIL-BS-WP-0010 | finished | — | workplans/RAIL-BS-WP-0010-weekly-legacy-meter-review-rollout.md |
 | workplan | RAIL-BS-WP-0011 | finished | — | workplans/RAIL-BS-WP-0011-legacy-meter-8h-capture-image-reconcile.md |
-| workplan | RAIL-BS-WP-0012 | active | — | workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md |
+| workplan | RAIL-BS-WP-0012 | finished | — | workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md |
 | task | RAIL-BS-WP-0007-T01 | todo | — | workplans/RAIL-BS-WP-0007-threephoenix-ha-cluster.md |
 | task | RAIL-BS-WP-0007-T02 | todo | — | workplans/RAIL-BS-WP-0007-threephoenix-ha-cluster.md |
 | task | RAIL-BS-WP-0007-T03 | todo | — | workplans/RAIL-BS-WP-0007-threephoenix-ha-cluster.md |
@@ -39,4 +39,4 @@
 | task | RAIL-BS-WP-0012-T01 | done | — | workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md |
 | task | RAIL-BS-WP-0012-T02 | done | — | workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md |
 | task | RAIL-BS-WP-0012-T03 | done | — | workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md |
-| task | RAIL-BS-WP-0012-T04 | wait | — | workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md |
+| task | RAIL-BS-WP-0012-T04 | done | — | workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md |

bin/railiance

@@ -5,6 +5,53 @@ set -euo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 PATH="${ROOT}/tools/cmd:${PATH}"
 
+resolve_rail_kubernetes_bin() {
+  if [[ -n "${RAILIANCE_RAIL_KUBERNETES_BIN:-}" ]]; then
+    if [[ -x "${RAILIANCE_RAIL_KUBERNETES_BIN}" ]]; then
+      printf '%s\n' "${RAILIANCE_RAIL_KUBERNETES_BIN}"
+      return 0
+    fi
+    echo "ERROR: RAILIANCE_RAIL_KUBERNETES_BIN is not executable: ${RAILIANCE_RAIL_KUBERNETES_BIN}" >&2
+    return 2
+  fi
+
+  local sibling="${ROOT}/../rail-kubernetes/bin/railiance"
+  if [[ -x "${sibling}" ]]; then
+    printf '%s\n' "${sibling}"
+    return 0
+  fi
+
+  return 1
+}
+
+run_compat_command() {
+  local cmd="$1"
+  shift || true
+
+  local delegate_bin=""
+  local resolve_status=0
+  if delegate_bin="$(resolve_rail_kubernetes_bin)"; then
+    exec "${delegate_bin}" "${cmd}" "$@"
+  else
+    resolve_status=$?
+  fi
+
+  if [[ "${resolve_status}" -eq 2 ]]; then
+    exit 1
+  fi
+
+  echo "WARN: rail-kubernetes delegate not found; using compatibility implementation from railiance-cluster" >&2
+  case "${cmd}" in
+    create-overlay) bash "$ROOT/tools/create_railiance_overlay_repo.sh" "$@" ;;
+    run) exec railiance-run "$@" ;;
+    deploy) exec railiance-stage2 deploy "$@" ;;
+    observe) exec railiance-stage2 observe "$@" ;;
+    promote) exec railiance-stage3 promote "$@" ;;
+    rollback) exec railiance-stage3 rollback "$@" ;;
+    *) echo "Unknown compatibility command: ${cmd}" >&2; exit 2 ;;
+  esac
+}
+
 usage() {
   cat <<'EOF'
 Usage: bin/railiance <command> [args]
@@ -16,12 +63,12 @@ Commands:
   gen-ssh-key   Generate SSH key and show public part
   cloudinit     Emit minimal cloud-init user-data
   init-repo     Idempotently furnish repo housekeeping
-  create-overlay Scaffold a Railiance overlay repo for an upstream app
+  create-overlay Delegate to rail-kubernetes or use local compatibility scaffold
-  run           Run Stage 1 local validation from railiance/app.toml
+  run           Delegate to rail-kubernetes or run local Stage 1 compatibility path
-  deploy        Plan/apply Stage 2 canary deployment
+  deploy        Delegate to rail-kubernetes or run local Stage 2 compatibility path
-  observe       Plan/run Stage 2 observation checks
+  observe       Delegate to rail-kubernetes or run local Stage 2 compatibility path
-  promote       Plan/apply Stage 3 stable promotion
+  promote       Delegate to rail-kubernetes or run local Stage 3 compatibility path
-  rollback      Plan/apply rollback to previous stable
+  rollback      Delegate to rail-kubernetes or run local Stage 3 compatibility path
   deploy-triage-robustness
                 Deploy ACTIVITY-WP-0016 and prove daily-triage validation
   admin-sync-smoke
@@ -49,12 +96,12 @@ case "$cmd" in
     ;;
   cloudinit) cat "$ROOT/cloudinit/user-data.yaml" ;;
   init-repo) bash "$ROOT/tools/furnish_railiance_repo.sh" ;;
-  create-overlay) bash "$ROOT/tools/create_railiance_overlay_repo.sh" "$@" ;;
+  create-overlay) run_compat_command create-overlay "$@" ;;
-  run) exec railiance-run "$@" ;;
+  run) run_compat_command run "$@" ;;
-  deploy) exec railiance-stage2 deploy "$@" ;;
+  deploy) run_compat_command deploy "$@" ;;
-  observe) exec railiance-stage2 observe "$@" ;;
+  observe) run_compat_command observe "$@" ;;
-  promote) exec railiance-stage3 promote "$@" ;;
+  promote) run_compat_command promote "$@" ;;
-  rollback) exec railiance-stage3 rollback "$@" ;;
+  rollback) run_compat_command rollback "$@" ;;
   deploy-triage-robustness) exec railiance-deploy-activity-core-triage-robustness "$@" ;;
   admin-sync-smoke) exec railiance-admin-sync-smoke "$@" ;;
   build-spore) bash "$ROOT/tools/build_spore.sh" ;;

docs/README.md

@@ -19,12 +19,14 @@ Use the sections below to keep those concerns separate.
 
 - [rail-kubernetes extraction map](rail-kubernetes-extraction-map.md)
 - [rail-kubernetes substrate profile](rail-kubernetes-substrate-profile.md)
+- [rail-kubernetes compatibility shim](rail-kubernetes-compatibility-shim.md)
 
 ## Transitional Workload-Contract Docs
 
 These docs describe the generic workload-on-Kubernetes contract. They are still
-hosted in this repo for compatibility, but they are targeted for extraction to
+hosted in this repo for compatibility, but canonical ownership now lives in
-future `rail-kubernetes`.
+`rail-kubernetes` and the cluster repo should keep only temporary copies or
+pointer docs during the migration window.
 
 - [Deployment lifecycle](deployment-lifecycle.md)
 - [Railiance app.toml contract](app-toml-contract.md)

docs/rail-kubernetes-compatibility-shim.md

@@ -0,0 +1,45 @@
+# rail-kubernetes Compatibility Shim
+
+## Purpose
+
+Record the migration-window behavior that keeps current
+`railiance-cluster/bin/railiance` users working while canonical ownership of
+the generic workload lifecycle commands moves to `rail-kubernetes`.
+
+## Delegated Commands
+
+The cluster-side shim covers only these generic rail commands:
+
+- `create-overlay`
+- `run`
+- `deploy`
+- `observe`
+- `promote`
+- `rollback`
+
+For those commands, `railiance-cluster/bin/railiance` now delegates to
+`rail-kubernetes/bin/railiance` when a configured or sibling checkout exists.
+
+Resolution order:
+
+1. `RAILIANCE_RAIL_KUBERNETES_BIN`
+2. sibling checkout at `../rail-kubernetes/bin/railiance`
+3. temporary local compatibility copy in `railiance-cluster`
+
+If `RAILIANCE_RAIL_KUBERNETES_BIN` is set but not executable, the shim fails
+closed.
+
+## Commands Not Covered
+
+These remain outside the handoff:
+
+- S2 substrate commands such as `backup` and `preflight`
+- 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`
+
+## Canonical Home
+
+The canonical rail-side migration contract lives in the sibling
+`rail-kubernetes` repo at `docs/cluster-compatibility-handoff.md`.

workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md

@@ -4,11 +4,11 @@ type: workplan
 title: "rail-kubernetes extraction from railiance-cluster"
 domain: financials
 repo: railiance-cluster
-status: active
+status: finished
 owner: codex
 topic_slug: railiance
 created: "2026-07-25"
-updated: "2026-07-25"
+updated: "2026-07-26"
 state_hub_workstream_id: "2b01ce91-35be-4947-832b-2f462c6ba472"
 ---
 
@@ -107,7 +107,7 @@ expectations, and explicit non-guarantees for wave 1.
 
 ```task
 id: RAIL-BS-WP-0012-T04
-status: wait
+status: done
 priority: medium
 state_hub_task_id: "fdc9fa63-bee2-4774-b92f-63cf7a315603"
 ```
@@ -120,6 +120,13 @@ 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