railiance-master/workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	related_repos	state_hub_workstream_id
RAILIANCE-WP-0017	workplan	Rail, Rapp, and Reef Repo Separation	financials	railiance-master	finished	codex	railiance	high	17	2026-07-25	2026-07-25	railiance-master railiance-cluster railiance-platform railiance-apps railiance-forge railiance-fabric railiance-infra railiance-hosts	dd794e38-6da0-4acd-8ad8-e00bd2aa62bc

RAILIANCE-WP-0017 - Rail, Rapp, and Reef Repo Separation

Goal

Turn the newly defined rail-*, rapp-*, and reef-* concepts into an executable migration plan for the current Railiance repo family, so the framework can evolve without leaving workload execution semantics, workload packaging, and substrate realities mixed into the existing ownership repos.

This workplan is explicitly cross-repo. It belongs in railiance-master because no single implementation repo can own the migration end to end.

Current Starting Point

The framework baseline is now recorded in railiance-master:

• docs/repository-axes.md
• docs/reef-substrate-model.md
• docs/adr/ADR-0001-repository-prefix-architecture.md

The repo is also now prepared and registered with State Hub as the architecture home for future multi-repo Railiance work.

The architectural direction is now further clarified:

• wave 1 is centered on rail-kubernetes as the default base rail
• new rails are introduced only for concrete workload needs with a sound runtime argument
• rail-knative is the first expected follow-on rail, driven by the need to support qonto-assistent, but only after the Kubernetes rail boundary is clean
• rapp-* repos are about managed wrapping and scaffolding, not ownership
• reef-* repos are about compute resources organized for a defined purpose
• mixed-rail reefs are acceptable early, but production-grade cases should prefer clearer substrate and primary-rail separation unless deliberately justified

The remaining problem is implementation reality:

• railiance-cluster still owns Kubernetes-specific workload lifecycle and overlay semantics that should eventually become rail-kubernetes
• first-class workload wrappers are still spread across railiance-apps, railiance-platform, and railiance-forge
• substrate reality is under-described and split between railiance-infra and railiance-hosts
• railiance-fabric and State Hub do not yet model rails, rapps, or reefs as first-class entities

Target Outcome

When this workplan is complete:

1. Railiance has a clear first migration target for rail-kubernetes.
2. The first set of rapp-* candidates is chosen and ordered.
3. The first reef-* rollout rule is chosen for current named substrates.
4. railiance-fabric and State Hub have a defined integration path for the new repo families.
5. The current repo set has an approved separation plan, not only a naming idea.

Boundaries

This workplan may define, sequence, and coordinate repo splits.

It must not silently move implementation content between repos without explicit repo-local follow-up workplans or commits in those repos.

Tasks

T01 - Record the framework repo-family baseline in railiance-master

id: RAILIANCE-WP-0017-T01
status: done
priority: high
state_hub_task_id: "7cb6769a-5557-46e5-8e20-c492e5049604"

Record the first canonical architecture baseline for:

• railiance-* as ownership repos
• rail-* as execution-contract repos
• rapp-* as managed workload package repos
• reef-* as substrate-boundary repos

Acceptance:

• railiance-master contains the baseline documents and ADR
• the reef-* model is explicitly defined and bounded against repo explosion

T02 - Prepare railiance-master as the cross-repo workplan home

id: RAILIANCE-WP-0017-T02
status: done
priority: high
state_hub_task_id: "17be5faa-cba2-4838-97af-dc3b79e0511b"

Prepare and register railiance-master in State Hub so cross-repo architecture work can live here as first-class workplans.

Acceptance:

• repo is classification-registered
• repo passes statehub fix-consistency
• workplan and architecture files can now be indexed from this repo

T03 - Define the rail-kubernetes extraction boundary

id: RAILIANCE-WP-0017-T03
status: done
priority: high
state_hub_task_id: "e25ea023-e2fe-44b9-96c1-cca19c65053f"

Define what moves from railiance-cluster into a future rail-kubernetes repo, and what must remain owned by railiance-cluster.

This is the wave-1 architecture task. It must treat rail-kubernetes as the default base rail for the current ecosystem rather than as one option among many equally urgent rails.

At minimum, decide the boundary for:

• railiance/app.toml
• promotion lifecycle semantics
• overlay repo pattern
• stage-1/2/3 tooling
• cluster-runtime prerequisites versus workload-runtime semantics
• the compatibility path future rails such as rail-knative will rely on

Acceptance:

• one written boundary contract names what railiance-cluster keeps
• one written boundary contract names what rail-kubernetes must own
• at least one migration-safe path exists that does not break current users
• the boundary leaves a coherent follow-on path for rail-knative without forcing knative design decisions into wave 1

2026-07-25: Added docs/rail-kubernetes-boundary.md and docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md. The boundary now names the retained S2 substrate scope, the extracted Kubernetes rail contract, the rehome-required workload-specific helpers, and a compatibility-preserving split sequence.

T04 - Identify and sequence the first rapp-* candidates

id: RAILIANCE-WP-0017-T04
status: done
priority: high
state_hub_task_id: "674b1a4f-2c5b-499c-b26f-9ed4f9f0861c"

Choose the first workload packages that should become first-class rapp-* repos instead of remaining embedded inside ownership repos.

This task must treat rapp-* as managed workload packaging for third-party or self-built workloads in the Railiance and Net Kingdom context. It must not turn rapp-* into an ownership mirror of existing railiance-* repos.

Candidate set to assess:

• Forgejo or Gitea from railiance-forge
• OpenBao from railiance-platform
• one user-facing S5 workload from railiance-apps

Acceptance:

• first-wave rapp-* candidates are named
• rationale is recorded for each chosen or deferred candidate
• split order is defined so ownership boundaries do not get weaker during migration
• each chosen candidate is justified as a managed wrapper and not as a new ownership home

2026-07-25: Added docs/rapp-first-wave-candidates.md and docs/adr/ADR-0003-rapp-first-wave-selection.md. The first-wave order is now rapp-openbao, then rapp-vergabe-teilnahme, with the forge workload explicitly deferred until the Gitea-versus-Forgejo package target is stable enough to avoid immediate wrapper churn.

T05 - Decide the first reef-* rollout for current substrates

id: RAILIANCE-WP-0017-T05
status: done
priority: medium
state_hub_task_id: "53c63266-fbcb-4644-86f4-042e7b80744e"

Apply the new reef model to the current Railiance substrate reality and decide whether the first rollout should be:

• reef-coulombcore
• reef-railiance01
• reef-workstation
• or a grouped substrate such as reef-ops-workstations

This task must also resolve the conceptual overlap between railiance-infra and railiance-hosts.

It should treat reefs as compute resources organized for a defined purpose and should explicitly decide how much multi-rail mixing is acceptable in early substrates such as RAILIANCE01.

Acceptance:

• first-wave reef repo set is chosen
• the rule for singleton versus grouped reef repos is applied to current hosts
• the railiance-hosts versus railiance-infra ambiguity has a documented direction
• any provisional terminology for transitional substrates is kept provisional unless the pattern is stable enough to canonize

2026-07-25: Added docs/reef-first-wave-rollout.md and docs/adr/ADR-0004-first-wave-reef-rollout.md. The first rollout is now reef-railiance01, reef-coulombcore, and reef-ops-workstations, with railiance-infra chosen as the canonical S1 ownership repo and transitional substrate nicknames intentionally left provisional.

T06 - Define railiance-fabric and State Hub adaptation for the new repo families

id: RAILIANCE-WP-0017-T06
status: done
priority: medium
state_hub_task_id: "4f47d000-6495-4163-8673-f339dd7ef41f"

Define the minimum graph and coordination changes needed so rails, rapps, and reefs are not only naming conventions but visible ecosystem entities.

Acceptance:

• railiance-fabric adaptation requirements are listed
• State Hub registration/indexing implications are listed
• the minimum fields or declarations needed in future rail-*, rapp-*, and reef-* repos are recorded

2026-07-25: Added docs/fabric-state-hub-adaptation.md. The minimum adaptation requirements now cover repo-family metadata, Fabric onboarding updates, typed service/relation vocabulary, and the smallest repo-local declaration surface future rail-*, rapp-*, and reef-* repos must expose.

T07 - Launch the first migration wave into concrete repo-local follow-up work

id: RAILIANCE-WP-0017-T07
status: done
priority: high
state_hub_task_id: "e762c05a-c6f1-439e-98e2-bf4d7b312a74"

Create the concrete follow-up workplans in the affected implementation repos for the first migration wave.

Acceptance:

• at least one repo-local workplan exists for rail-kubernetes
• at least one repo-local workplan exists for a first rapp-* extraction
• at least one repo-local workplan exists for a first reef-* rollout or substrate cleanup
• this master workplan can then govern sequencing rather than holding all implementation detail itself

2026-07-25: Added the first repo-local follow-up workplans:

• railiance-cluster/workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md
• railiance-platform/workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md
• railiance-infra/workplans/RAIL-HO-WP-0007-first-reef-rollout-and-s1-canonicalization.md

Exit Criteria

• The architecture baseline is recorded in railiance-master
• railiance-master is registered and synced with State Hub
• rail-kubernetes boundary is written and approved
• first rapp-* candidates and split order are written and approved
• first reef-* rollout decision is written and approved
• Fabric and State Hub adaptation requirements are written
• first migration-wave follow-up workplans exist in the affected repos

Notes

This workplan is intended to stay small at the framework level. Once a split or migration has a concrete owner, the implementation detail should move into the relevant repo-local workplan rather than expanding this file into a second control plane.