Launch first repo-family materialization wave

README.md

@@ -14,6 +14,7 @@ recorded before they are spread across implementation repos.
 - [docs/rapp-first-wave-candidates.md](docs/rapp-first-wave-candidates.md)
 - [docs/reef-first-wave-rollout.md](docs/reef-first-wave-rollout.md)
 - [docs/fabric-state-hub-adaptation.md](docs/fabric-state-hub-adaptation.md)
+- [docs/repo-family-bootstrap-contract.md](docs/repo-family-bootstrap-contract.md)
 - [docs/adr/ADR-0001-repository-prefix-architecture.md](docs/adr/ADR-0001-repository-prefix-architecture.md)
 - [docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md](docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md)
 - [docs/adr/ADR-0003-rapp-first-wave-selection.md](docs/adr/ADR-0003-rapp-first-wave-selection.md)

SCOPE.md

@@ -65,15 +65,16 @@ Railiance repos and cannot be owned cleanly by only one of them.
 
 ## Current State
 
-- Status: maintained / evolving
+- Status: active / evolving
-- Implementation: architecture baseline documents are present and the first cross-repo separation workplan has been completed and handed off to sibling repos
+- Implementation: architecture baseline documents are present and the first concrete repo-family materialization wave is now being coordinated from this repo
 - Stability: evolving
 - Usage: internal Railiance framework architecture home and handoff point for cross-repo planning
 
 The repo now holds the canonical framework decisions and boundary documents for
 separating `rail-*`, `rapp-*`, and `reef-*` concerns out of the existing
-Railiance repos. Active implementation follow-up continues in the sibling
+Railiance repos. It also now governs the first implementation wave that turns
-ownership repos.
+those repo families into concrete repos while downstream ownership repos retain
+their implementation responsibility.
 
 ---
 

WORK-RECORDS.md

@@ -9,6 +9,7 @@
 | Kind | ID | Status | Lane | Source |
 | --- | --- | --- | --- | --- |
 | workplan | RAILIANCE-WP-0017 | finished | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md |
+| workplan | RAILIANCE-WP-0018 | active | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md |
 | task | RAILIANCE-WP-0017-T01 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md |
 | task | RAILIANCE-WP-0017-T02 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md |
 | task | RAILIANCE-WP-0017-T03 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md |
@@ -16,3 +17,9 @@
 | task | RAILIANCE-WP-0017-T05 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md |
 | task | RAILIANCE-WP-0017-T06 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md |
 | task | RAILIANCE-WP-0017-T07 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md |
+| task | RAILIANCE-WP-0018-T01 | done | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md |
+| task | RAILIANCE-WP-0018-T02 | progress | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md |
+| task | RAILIANCE-WP-0018-T03 | wait | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md |
+| task | RAILIANCE-WP-0018-T04 | wait | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md |
+| task | RAILIANCE-WP-0018-T05 | wait | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md |
+| task | RAILIANCE-WP-0018-T06 | wait | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md |

docs/repo-family-bootstrap-contract.md

@@ -0,0 +1,183 @@
+# First-Wave Repo Family Bootstrap Contract
+
+Date: 2026-07-25
+
+## Purpose
+
+Define the minimum bootstrap contract for the first concrete `rail-*`,
+`rapp-*`, and `reef-*` repos.
+
+This document exists to keep the first repo-materialization wave coherent.
+Without a shared bootstrap contract, each new repo would improvise its own file
+layout, declaration shape, and metadata vocabulary, which would weaken the
+architecture as soon as the new repo families become real.
+
+## Design Goal
+
+The first concrete repos should be:
+
+- small enough to create quickly
+- explicit enough to be queryable by Fabric and State Hub
+- narrow enough to avoid reintroducing ownership ambiguity
+
+The goal is not to design a perfect final schema before the first repo exists.
+The goal is to establish a minimal, repeatable repo baseline that can evolve
+without fragmenting.
+
+## Required Repo Baseline
+
+Every first-wave `rail-*`, `rapp-*`, and `reef-*` repo should start with:
+
+- `.repo-classification.yaml`
+- `README.md`
+- `INTENT.md`
+- `SCOPE.md`
+- `AGENTS.md`
+- `CLAUDE.md`
+- `workplans/`
+- `workplans/archived/`
+- one repo-family declaration file under `declarations/`
+
+If a repo needs implementation code, manifests, charts, or automation, those
+can be added after the bootstrap baseline is in place.
+
+## Required Classification Metadata
+
+The following metadata should be present either directly in
+`.repo-classification.yaml` or in the first declaration file and projected from
+there into Fabric and State Hub:
+
+- `repo_family`
+- `ownership_repo`
+- `primary_rail` when applicable
+- `supported_rails` when applicable
+- `substrate_kind` when applicable
+
+The source-of-truth rule is:
+
+- repo-local declarations define the domain facts
+- registry metadata reflects the smallest useful projection of those facts
+
+Do not let registry-only metadata become the only place where a repo family is
+described.
+
+## Required Declaration Files
+
+The first wave should standardize one obvious declaration path per repo family.
+
+### `rail-*`
+
+Path:
+
+`declarations/rail.yaml`
+
+Minimum fields:
+
+- `rail_id`
+- `ownership_repo`
+- `execution_architecture`
+- `substrate_prerequisites`
+- `supported_rollout_modes`
+- `compatibility_notes`
+
+### `rapp-*`
+
+Path:
+
+`declarations/rapp.yaml`
+
+Minimum fields:
+
+- `rapp_id`
+- `workload_identity`
+- `ownership_repo`
+- `supported_rails`
+- `runtime_dependencies`
+- `rollout_contract`
+- `smoke_contract`
+- `rollback_contract`
+
+### `reef-*`
+
+Path:
+
+`declarations/reef.yaml`
+
+Minimum fields:
+
+- `reef_id`
+- `substrate_kind`
+- `ownership_repo`
+- `lifecycle_state`
+- `criticality`
+- `hosted_rails`
+- `bound_rapps`
+- `primary_rail`
+
+## Required Boundary Rules
+
+The first concrete repos must respect the architecture boundaries already
+defined in `railiance-master`.
+
+### `rail-*`
+
+- A rail repo owns an execution contract, not substrate bootstrap.
+- `rail-kubernetes` must not absorb S2 cluster provisioning, admission
+  controller ownership, or generic substrate hardening from
+  `railiance-cluster`.
+- A rail repo may own generic workload-on-that-rail semantics, compatibility
+  guidance, and rail-local helper tooling.
+
+### `rapp-*`
+
+- A `rapp-*` repo owns managed workload packaging and scaffolding.
+- A `rapp-*` repo must not become the long-term ownership home of the platform
+  or application domain around that workload.
+- Shared policy, tenant governance, or platform-wide credential semantics stay
+  in the owning `railiance-*` repo.
+
+### `reef-*`
+
+- A reef repo owns one durable substrate boundary.
+- A reef repo must not be created automatically for every machine.
+- Grouped reefs remain preferred when the machines are managed as one class,
+  such as workstation fleets.
+
+## First-Wave Candidates
+
+The first materialization wave should target:
+
+- `rail-kubernetes`
+- `rapp-openbao`
+- `reef-railiance01`
+
+The follow-on first-wave candidates after those anchors are stable:
+
+- `rapp-vergabe-teilnahme`
+- `reef-coulombcore`
+- `reef-ops-workstations`
+
+This keeps the first concrete rollout narrow while still covering all three new
+repo families.
+
+## Integration Expectations
+
+The first-wave repos should be able to participate in:
+
+- State Hub workplan indexing
+- Fabric repository registration
+- repo-family metadata projection
+- later relation projection such as `supports_rail`, `hosts_rail`,
+  `binds_rapp`, and `governed_by`
+
+They do not need a fully mature graph model on day one, but they do need enough
+structured metadata to avoid becoming opaque one-off repos.
+
+## Outcome
+
+The bootstrap contract for the first repo-family wave is:
+
+- one repeatable baseline file set
+- one obvious declaration path per repo family
+- one clear metadata projection path into Fabric and State Hub
+- one narrow initial rollout set covering `rail-*`, `rapp-*`, and `reef-*`

workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md

@@ -0,0 +1,236 @@
+---
+id: RAILIANCE-WP-0018
+type: workplan
+title: "First-Wave Repo Family Materialization"
+domain: financials
+repo: railiance-master
+status: active
+owner: codex
+topic_slug: railiance
+planning_priority: high
+planning_order: 18
+created: "2026-07-25"
+updated: "2026-07-25"
+related_repos:
+  - railiance-master
+  - railiance-cluster
+  - railiance-platform
+  - railiance-infra
+  - railiance-fabric
+state_hub_workstream_id: "054a494c-e430-4164-b2c3-e32e759cc3e0"
+---
+
+# RAILIANCE-WP-0018 - First-Wave Repo Family Materialization
+
+## Goal
+
+Turn the completed separation architecture into the first concrete
+`rail-*`, `rapp-*`, and `reef-*` repo materialization wave.
+
+This workplan governs the first implementation wave that makes the new repo
+families real rather than only defined. It stays in `railiance-master` because
+the sequencing still spans multiple ownership repos and Fabric integration.
+
+## Why This Exists
+
+`RAILIANCE-WP-0017` completed the architecture baseline and launched the first
+repo-local follow-up workplans.
+
+What is still missing is the shared control plane for:
+
+- creating the first concrete repo-family baselines
+- keeping their boundaries consistent across repos
+- aligning repo-local declarations with Fabric and State Hub ingestion
+- preventing the first repo creations from drifting into ad hoc local patterns
+
+## Current Starting Point
+
+The architecture baseline already exists in `railiance-master`:
+
+- `docs/repository-axes.md`
+- `docs/rail-kubernetes-boundary.md`
+- `docs/rapp-first-wave-candidates.md`
+- `docs/reef-first-wave-rollout.md`
+- `docs/fabric-state-hub-adaptation.md`
+
+The first implementation follow-up work also already exists:
+
+- `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`
+- `railiance-fabric/workplans/RAIL-FAB-WP-0025-rail-rapp-reef-fabric-adaptation.md`
+
+Fabric now has first repo-family-aware repository metadata, but the ecosystem
+still lacks:
+
+- the first actual `rail-*` repo
+- the first actual `rapp-*` repo
+- the first actual `reef-*` repo
+- relation projection for rail/rapp/reef topology
+
+## Target Outcome
+
+When this workplan is complete:
+
+1. Railiance has a repeatable bootstrap contract for first-wave `rail-*`,
+   `rapp-*`, and `reef-*` repos.
+2. The first concrete `rail-kubernetes` repo exists and is registered.
+3. The first concrete `rapp-openbao` repo exists and is registered.
+4. The first concrete `reef-railiance01` repo exists and is registered.
+5. Fabric can project the minimum rail/rapp/reef relation topology needed to
+   answer placement questions.
+
+## Boundaries
+
+This workplan may coordinate repo creation, repo-family bootstrap, and graph
+integration across Railiance repos.
+
+It must not weaken the existing ownership boundaries:
+
+- `railiance-cluster` remains the S2 ownership home
+- `railiance-platform` remains the S3 ownership home for OpenBao
+- `railiance-infra` remains the canonical S1 ownership home for first-wave reefs
+- `railiance-fabric` remains the implementation home for graph ingestion and
+  projection
+
+## Tasks
+
+## T01 - Publish the first-wave repo bootstrap contract
+
+```task
+id: RAILIANCE-WP-0018-T01
+status: done
+priority: high
+state_hub_task_id: "d6ba9286-222d-49d2-83e9-fd251c534dde"
+```
+
+Record the minimum bootstrap contract future `rail-*`, `rapp-*`, and
+`reef-*` repos should follow so the first materialization wave does not invent
+three incompatible patterns.
+
+Acceptance:
+
+- one framework document defines the minimum file baseline
+- one framework document defines the first declaration path per repo family
+- the metadata projection rule into Fabric and State Hub is named
+
+2026-07-25: Added `docs/repo-family-bootstrap-contract.md`.
+
+## T02 - Launch the first `rail-kubernetes` repo materialization
+
+```task
+id: RAILIANCE-WP-0018-T02
+status: progress
+priority: high
+state_hub_task_id: "726a0c5c-2fa5-4bb9-a730-3200abc40ac8"
+```
+
+Create the concrete repo bootstrap and extraction path for `rail-kubernetes`
+using the boundary already defined in `railiance-master` and the repo-local
+follow-up work already opened in `railiance-cluster`.
+
+Acceptance:
+
+- the new repo has the required baseline files
+- the repo declares the Kubernetes rail contract in source-controlled form
+- the compatibility path from `railiance-cluster` is preserved
+- the repo is ready for Fabric and State Hub registration
+
+## T03 - Launch the first `rapp-openbao` repo materialization
+
+```task
+id: RAILIANCE-WP-0018-T03
+status: wait
+priority: high
+state_hub_task_id: "3e46e1bd-c730-4e41-a00a-6aa7a4645023"
+```
+
+Create the concrete repo bootstrap and workload-package declaration for
+`rapp-openbao` without letting the package repo absorb platform ownership.
+
+Acceptance:
+
+- the new repo has the required baseline files
+- the repo declares OpenBao as a managed workload package
+- the repo declares supported rails and rollout/smoke/rollback contract
+- the remaining ownership boundary with `railiance-platform` stays explicit
+
+## T04 - Launch the first `reef-railiance01` repo materialization
+
+```task
+id: RAILIANCE-WP-0018-T04
+status: wait
+priority: medium
+state_hub_task_id: "f6f2ea73-0ff3-4cfa-b7a7-7b71db3afb4a"
+```
+
+Create the concrete repo bootstrap and substrate declaration for
+`reef-railiance01` as the first durable reef repo.
+
+Acceptance:
+
+- the new repo has the required baseline files
+- the repo declares substrate kind, lifecycle, criticality, hosted rails, and
+  primary rail
+- the repo stays compatible with the canonical S1 ownership role of
+  `railiance-infra`
+
+## T05 - Add relation projection for rails, `rapp`s, and reefs in Fabric
+
+```task
+id: RAILIANCE-WP-0018-T05
+status: wait
+priority: medium
+state_hub_task_id: "ef999db5-e75e-467a-a72a-d45fda2b6fa7"
+```
+
+Extend Fabric beyond repo-family-aware metadata so it can project the minimum
+rail/rapp/reef relation topology.
+
+Acceptance:
+
+- Fabric can project `supports_rail`
+- Fabric can project `hosts_rail`
+- Fabric can project `binds_rapp`
+- Fabric can project `governed_by`
+- the projection path is grounded in repo-local declarations rather than
+  registry-only guesses
+
+## T06 - Verify first-wave registration and coordination end to end
+
+```task
+id: RAILIANCE-WP-0018-T06
+status: wait
+priority: medium
+state_hub_task_id: "5834f122-b9e9-41c1-93e9-d5525cd720bf"
+```
+
+Verify that the first concrete repos participate cleanly in:
+
+- State Hub registration and indexing
+- Fabric registration and graph projection
+- workplan tracking across ownership repo and repo-family repo boundaries
+
+Acceptance:
+
+- the first concrete repos are visible to State Hub
+- the first concrete repos are visible to Fabric
+- cross-repo ownership and runtime relations are queryable
+- the wave can continue to second candidates without redefining the bootstrap model
+
+## Exit Criteria
+
+- [x] The first-wave bootstrap contract is published
+- [ ] `rail-kubernetes` exists as a first-class repo baseline
+- [ ] `rapp-openbao` exists as a first-class repo baseline
+- [ ] `reef-railiance01` exists as a first-class repo baseline
+- [ ] Fabric projects the minimum rail/rapp/reef relation topology
+- [ ] State Hub and Fabric can coordinate the first concrete repo-family wave end to end
+
+## Notes
+
+This workplan should stay focused on the first concrete repo-family wave.
+
+Second-wave candidates such as `rapp-vergabe-teilnahme`, `reef-coulombcore`,
+or a future `rail-knative` should be launched only after the first wave proves
+the bootstrap contract, registration path, and relation model.