Finish rail-kubernetes bootstrap handoff

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:
 

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
 
 ---
 

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 |

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

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.

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.

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