Launch first repo-family materialization wave

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